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S  ABSTRACT 

j>  The  cost  of  software  is  fast  besoming  a  major  slice  of  DDD's 

^  automated  data  processing  budget.  Most  of  this  oost  is 

|!  directly  related  to  the  maintenance  of  existing  software.  A 

primary  cause  is  poor  or  non-existant  documentation  which 
leads  to  high  costs  when  it  coses  time  to  change  the  sof t- 
ware  to  correct  errors,  add  enhancements,  or  to  comply  with 

fi 

/  changes  in  Federal  regulations/DOD  policies. 

This  thesis  looks  at  the  various  software  engineering 
technigues  available  to  programmers  and  managers  for  the 
development  of  software  documentation.  A  set  of  guidelines 
for  an  "ideal”  program  maintenance  manual  is  proposed.  These 
guidelines  are  based  on  current  DoD  standards,  examples  of 
software  maintenance  manuals  from  industry,  and  applications 
of  currant  software  engineering  practices. 
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km  THE  NEED  FOB  DOCUHENT  ATION 

k  recent  Government  Accounting  Dffice  report,  reviewing 
computer  software  maintenance  in  Federal  ADP  agencies, 
produced  some  inreresting  observations  'Ref.  1]. 

1.  Two  thirds  of  the  programmers  at  15  Federal  ADP  agen¬ 
cies  spent  their  time  on  software  a amter.ance. 

2.  The  Department  of  Defense  will  spend  approximately  $3 
billion  in  198  1  on  software. 

3.  Agencies  have  m$de  little  effort  to  effectively 
manage  and  minimize  the  resources  required  to  main¬ 
tain  computer  software. 

4.  Software  is  often  maintained  by  oaople  who  did  not 
develop  it. 

5.  Poor  documentation  often  results  in  rebuilding  an 
entire  system  of  programs  because  understanding  ana 
modifying  an  existing  program  may  be  more  trouble  and 
expense  then  building  a  new  one. 

The  Federal  Government  is  not  alone  in  its  software  mainte¬ 
nance  ’crises'.  All  ADP  users,  including  private  industry, 
are  being  swallowed  up  by  the  "tar- pits  of  software  manage¬ 
ment"  as  Fred  Brooks  has  so  vividly  described  [Ref.  2].  The 
costs  to  the  government  and  private  industry,  in  terms  of 
dollars  and  manpower,  is  increasing  at  an,  alarming  rate. 
Costs  for  software  (procurement  and  maintenance)  are 
expected  to  reach  $200  billion  by  1985.  OOD  estimates  it 
will  spend  33C  billion  by  1990  for  embedded  software  alone 
[Ref.  3,4]. 

A  large  share  of  these  costs  are  for  software  mair.ts- 


r.  a  n  c  e 

(see  Figure  1. 

1)  • 
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There  are  many  reasons  for  the  wide  variation  in  effort 
being  devoted  to  software  maintenance,  however,  a  definition 
of  maintenance  should  be  presented  first.  Software  mainte¬ 
nance  is  best  defined  as: 


That  activity  which  is  concerned  with  making  changes  to 
software  for  the  purpose  of  improving  or  correcting  the 
software  without  introducing  new  errors  [  Bef .  15]. 


Despite  the  fact  that  large  amounts  of 
resources  are  spent  on  software  maintena 
comprehend  the  underlying  reasons.  The 
issues  behind  the  problems  of  software  aa 


•  Maintenance  is  considered  less  glam 
and  challanging  as  compared  to 
programming;  hence,  there  is  li 
computer  personnel  to  become  invol 
activities  (or  document  their  time 
maintenance) . 

•  During  development  it  is  often  too  e 
to  fcrsee  problems  which  may  occur 
as  a  consequence  maintainability  (ti 
ware  which  makes  maintenance  ac 
perform)  is  not  provided  for  in  the 

•  Project  management  dees  not  always  r 
tainability  considerations  should  b 
of  the  design  process. 

•  It  is  very  difficult  to  modify  or 
furs  of  a  orogram  arter  the  program 
[Ref.  15] 

Weapon  system  software  a  .id  real-ti 
used  extensively  by  the  Department  of  Def 
from  similar  problems  [Ref.  16].  De  Roz 
tiat  Air  Force  avionics  software  cost 
instruction  to  develop,  but  maintsnanc 
$4,000  oer  instruction.  SAGS,  a  military 


manpower  and  other 

ice,  few  managers 

re  are  four  basic 

iatenance: 

o  ro  us,  interesting 
system  design  ana 
t tie  incentive  for 
ved  in  maintenance 
and  effort  spent  on 

arly  in  the  project 
during  maintenance; 
e  preoerty  of  soft- 
tivities  easy  to 
system  design. 

ecogr.ize  that  tnain- 
e  an  integral  part 


simplify  the  ? touc¬ 
hes  been  written. 


avionics  software  cost: 


an  average  annual  cost  of  20  million  doll 
of  operation  compared  to  an  original  lave 
million  dollars  [Ref.  18]. 


.me  system  software 
ease  (DOD)  suffers 
:e  *  Ref.  17]  reports 
.3  about  $75  per 
:s  costs  are  around 
defense  system,  had 
.are  after  ter.  years 
ilopment  cost  of  250 


The  need  for  efficient,  cost  effecti/e  software  mainte¬ 
nance  is  important  because  "....of  the  need  to  keep  DOD 
real-time  weapon  system  softwace  operating  as  error  free  as 
possible  and  the  need  to  check  the  escalating  cost 
associated  with  modifying  this  software"  *  Ref .  16]. 

Good  documentation  is  seen  as  one  of  the  best  tools  for 
improving  software  maintenance  *  Hef.  19].  In  general,  docu¬ 
mentation  serves  as  a  means  of  communication  within  an 
organization,  especially  over  time.  Documentation  facili¬ 
tates  the  training  of  new  personnel  and  aids  in  modification 
of  a  software  system  by  people  other  than  the  original 
development  programmers.  Silbey  [Ref.  23]  sees  documenta¬ 
tion  as  addressing  three  primary  groups  of  people;  managers, 
programmers/system  analysts,  and  users.  3e  also  argues  that 
the  software  documentation  must  be  claac,  comprehensive, 
detailed  and  well  structured  in  order  to  be  used  effec¬ 
tively.  Good  documentation  can  and  must  provide  a  great  deal 
of  useful  information.  Specifically,  this  information  has  to 
communicate  to  the  maintenance  personnel  enough  detail  so 
that  enhancements  and  chances  to  the  software  can  be  easily 
made  and  do  not  produce  unwanted  effects  in  other  pacts  of 
the  system  [Ref.  21].  Table  I  lists  examples  of  the  types 
of  information  needed  in  documentation. 

Documentation  has  several  important  uses  beyond  a 
general  description  of  code.  During  the  software  development 
phase  it  is  used  for  communication  between  members  of  the 
design  team,  for  training  new  personnel  assigned  to  the 
progect  and  as  a  basis  for  design  reviews.  During  tie  soft¬ 
ware  maintenance  period  the  documentation  serves  again  as  a 
training  base,  a  guide  for  modification  and  error  checking, 
as  an  organized  collection  of  design  information,  and  as  a 
historical  "race  of  the  software's  production  and  operation. 

<J e  wish  to  emphasize  tne  necessity  of  considering 
the  generation  of  timely  do c umen tarred  as  an  i.nteara^ 
pcrtror.  cf  the  software  development  process  [Ref.  22 1. 


12 


< 


5 

1 

'> 

B 


TABLE  I 

Information  Documentation  Provides 


-A  historical  record  of  software  system  development. 


-A  detailed  analysis  of  software  systen  design. 


-A  veil  structured  sourc?  code  listing  with  comments 
on  logic  and  processing  flows. 


-Identification,  logical,  and  physical  characteristics 
of  the  Data  Base. 


-  Requirements,  operating  environment,  and  design 
characteristics  of  the  systen. 


-Written  instructions  for  non-AD?  personnel  that 
explains  what  the  system  (software  and  hardware) 
does  and  how  to  use  it. 


-Format  of  input  data  and  output  reports. 


-Technical  information  about*  data  collection 
requirements. 


-Detailed  specifications,  descriptions,  and  procedures 
for  all  tests  and  test  data. 


Documentation  is  an  important  product  of  sound  software 
engineering  design  rather  than  a  simple  bv-proiuct  of 
design.  Documentation  has  to  be  clear  and  concise.  The  docu¬ 
mentation  format  has  to  be  convenient  and  simple  to  use.  rhe 
documentation  has  to  be  organized  in  a  hierchical  fashion  ir. 
the  same  manner  that  the  code  is  structured.  All  design 
decisions  and  their  impact  has  to  be  e< plained,  and  the 
methodology  for  modifications  decided  in  advance.  Version 
control,  and  the  accounting  methods  for  n edification  to  the 
software,  has  to  be  thorough  [Ref.  23]. 
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How  much  ar.d  what  types  of  documentation  must  be  decided 
during  the  the  design  phase  of  system  development.  Much  to 
often  these  decisions  have  been  put  off  until  late  in  the 
system  development  cycle  which  cesuLts  in  poor  or 
non-existant  documentation  [Ref.  1]. 

If  we  are  to  improve  the  maintainability  of  large  soft¬ 
ware  systems  we  must  also  "design  for  change"  as  Parnas 
suggests  [Ref.  24].  This  includes  designing  good  documenta¬ 
tion  to  tell  us  what  a  software  system  does  and  how  it  does 
it. 

B.  PURPOSE  AND  ORGANIZATION  OP  THESIS 

The  purpose  of  this  thesis  is  two-foLd.  First  it  will 
examine  and  review  Federal  and  Department  of  Defense  direc¬ 
tives  on  standards  for  documentation.  Included  will  be  a 
summary  of  the  various  techniques  of  documentation  from  the 
technical  literature.  Second,  a  design  for  a  Programmer's 
Maintenance  Manual  will  be  presented  which  incorporates  the 
latest  concepts  in  software  engineering.  The  reasons  behind 
a  particular  design  and  the  benefits  to  be  gained  will  be 
di scussed. 

Chapter  II  of  the  thesis  will  review  the  concept  of  the 
software  life  cycle  and  how  software  maintenance  activities 
relate  to  different  life  cycLe  pnases.  A  discussion  of 
current  DOD  directives  in  software  management  that  govern 
weapon  system  software  will  be  given  here.  Techniques 
currently  available  for  programmers  and  software  contractors 
for  documentation  will  be  described  in  Ciapter  III.  These 
techniques  include  methods  for  representing  prcaran  logic 
such  as  structured  programming,  data  structures  and 
commented  program  listings. 


Chapter  17  contains  a  inscription  of  a  programmer's 
Maintenance  Manual  based  on  ODD  requirenents  for  software 
documentation  and  recommendations  for  changes  to  such  a 
manual.  The  manual  is  designs!  from  the  point  of  view  that 
the  program  listing  now  provides  a  great  deal  of  "self- 
documentation"  resulting  froa  advances  in  structured 
programming  techniques.  In  addition  the  purposes  and  goals 
of  a  manual  in  general  are  presented  with  a  view  that  any 
manual  should  be  designed  for  its  intended  user. 

Finally,  Chapter  V  will  provide  conclusions  and  recom¬ 
mendations.  An  appendix  contains  a  copy  of  the  currant  DoD 
standard  for  a  program  maintenance  nanual. 
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A.  THE  SOFTWARE  LIFE-CYCLE 


All  software,  tactical  weapon  systen  and  genacal  data 
processing,  must  go  through  several  phasas  or  steps  from  the 
time  a  need  for  a  software  system  is  conceived  to  the  point 
where  the  system  is  operational.  This  series  of  steps  is 
generally  referred  to  as  the  software  life  cycle.  The 
different  phases  of  the  life  cycle  have  various  names  when 
discussed  in  the  literature.  Many  representations  of  the 
life  cycle  are  described.  Figure  2.1  depicts  one  such  model 
based  on  the  well  understood  DOD  system  life  cycle  as 
presented  in  DOD  Instruction  5330. 1.  Figure  2.2  represents  a 
more  general  approach  to  the  life  cycle  phases. 

1.  Software  Development 

In  order  to  understand  better  what  must  be  done  to 
create  a  software  system,  an  informal  description  of  each 
phase  is  provided  [Ref.  25]. 

a.  System  Feasibility  and  Analysis  Phase 


The  eventual  user  of  a  system  discovers 
for  which  a  computer  based  information  system  or 
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V  aliiation 
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Fine  Tuning 

Support 

Maintenance 

Mo  aif ication 

Figure  2.1  DOD  Software  Life  CYcle  Model. 

b.  Requirements  Specification  Phis? 

Functional  descriptions  of  the  system  are  devel¬ 
oped  using  a  particular  formal  methodology.  Constraints  or. 
the  system's  structure  and  resource  usage  are  identified. 
Economic  constraints  on  the  development  process  itself  are 
stated.  This  phase  may  be  an  iterative  process  that  oscil¬ 
lates  between  the  statement  of  s pecif icati ons  and  refinement 
cf  the  design.  Documentation  standards  and  management  objec¬ 
tives  should  be  defined  ana  listed.  This  phase  is  to  clearly 
and  concisely  state  what  the  system  is  to  do  -  not  how  to  do 


c.  Product  Design  Phase 

Working  from  the  specifications  the  overall 
hardware/software  architecture  is  conceived.  The  underlying 
structure  of  the  problem  to  which  this  system  will  be  a 
solution  is  sought  out.  When 


I  —  >1  Product 
|  Design 


-- >  Detailed 
Design 


-->1  Validation  | 


— > I  Code  and 


Debug 


Software  Development 


I  —  >|  lest  and  I 

I  Integration  | 

ilopment 


| — >|  Maintenance  | - - > |  Decommission 


|  Modifications  |< - 1  j - >|  Enhancements  | 


0  peratio  ns 


Figure  2.2  Software  Life  3ycle--Seneral  Schematic. 

gr.  of  the  system  is  devised.  The  design  is  necessarily 
gross  abstract  level  cf  detail.  The  parts  cf  the  system 
their  relationships,  the  basic  algorithms  tnat  the 
m  will  use,  and  the  major  data  representations  that 
be  needed  are  created.  During  this  phase  the  basic 
est  plan  is  developed,  preferrably  by  an  independent  design 


d.  Detailed  Design  Phase 


The  major  parts  of  the  design  are  now  refined  in 
detail.  Precise  algorithms  and  data  strictures  are  defined 
and  spelled  out.  If  not  already  done  in  the  Product  Design 
Phase,  decisions  as  to  which  parts  of  the  system  will  be  in 
software  and  which  in  hardware  are  made.  Both  detail  design 
and  product  design  may  require  several  levels  of  refinement 
and  reiteration. 

e.  Validation  Phase 

At  this  point  in  the  development  a  checlc  must  be 
made  to  ensure  the  design,  ia  ail  details,  fulfills  the 
specificat ions. 

f.  Programming,  Code  ana  Debug  Phase 

Encoding  of  algorithms  and  data  representations 
is  accomplished  in  this  phase.  Individual  modules  are 
prepared  and  tested  individually.  All  oasic  debugging  is 
completed  where  possible.  Seme  bugs  may  not  appear  until  all 
the  system  parts  are  executed  together. 

g.  Integration/System  Testing  Phase 

All  ceded  modules  are  placed  together  along  with 
a  sample  data  base.  This  produces  a  physical  realization  of 
the  design.  Integration  of  all  the  parts,  system  testing 
according  to  the  system  test  plan,  and  performance  evalua¬ 
tion  is  accomplished.  In  many  rases  a  good  deal  of  redesign 
and  reimplementation  may  tafce  place  a;  this  time  to  forte 
the  actual  system  to  conform  to  the  specifications  and 
initial  requirements. 


2 .  Software  Oper  ation 

Everything  that  happens  after  the  software  system  is 
finished,  delivered  and  finally  accepted  by  the  user  falls 
into  the  operational  half  of  the  life  cycle. 

a.  Maintenance  Phase 

Tauseworthe  offers  a  definition  of  maintenance 
as  "alterations  to  the  software  during  the  post  delivery 
period  that  do  not  require  a  reinitiation  of  the  software 
development  cycle"  [Ref.  26].  tie  also  views  the  maintenance 
phase  as  any  software  related  activity,  principally  suppor¬ 
tive  in  form,  which  keeps  the  software  system  operational 
within  its  functional  specif icat ions.  The  main  activity  of 
maintenance  prcgramers  is  corrective  in  nature,  commonly 
referred  to  as  debugging.  Tauseworthe  considers  enhancements 
as  essentially  changes  to  the  specifications  which  enable 
the  software  .to  perform  either  a  new  task  or  a  different  but 
similar  •‘•ask.  In  each  case  the  functional  scope  of  the 
program  changes. 

Swanson  [Ref.  27]  a  isti  r.guisa  es  between  three 
types  of  software  maintenance;  corrective  maintenance,  adap¬ 
tive  maintenance  and  perfective  maintenance.  Corrective 
maintenance  is  performed  in  response  to  failures  such  as  the 
abnormal  termination  of  a  program  or  the  failure  to  meet 
performance  criteria.  Adaptive  maintenance  is  performed  in 
response  to  changes  in  environments  such  as  the  installation 
of  a  new  generation  of  system  lardware.  Perfective  mainte¬ 
nance  is  performed  to  make  the  program  a  more  perfect  design 
implementation.  For  example  to  improve  processing  efficiency 
or  to  add  new  features. 

Other  authors  feel  maintenance  has  only  two 
basic  components;  modifications  and  enhancements. 
Modifications  are  any  changes  to  existing  functions  to 
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correct  bugs  and  meet  specifications.  Enhancements  are  addi¬ 
tions  o£  new  functions  that  were  in  the  original  design  but 
never  implemented  or  were  added  as  a  result  of  an  iteration 
of  the  development  cycle  [Ba£.  25].  Modifications  and 
enhancements  will  be  the  terms  used  in  this  thesis  to  refer 
to  software  maintenance. 

A  more  accurate  and  definitive  model  of  the 
maintenance  phase  of  the  software  life  cycle  and  of  the  life 
cycle  itself  has  been  proposed  by  the  Rome  Air  Development 
Center  [Bef.  28].  Figure  2.3  illustrates  two  important 
items  concerning  this  model.  The  first  is  that  the  process 
of  software  development  is  highly  interactive  (indicated  by 
feedback  arrows)  in  order  to  incorporate  new  requirements 
and  changes  to  software  specifications.  Secondly,  and  more 
important,  it  emphasizes  the  importance  of  the  maintenance 
phase.  The  model  indicates  that  maintenance  phases  are  to  go 
through  the  same  iterative  steps  shown  for  software  develop¬ 
ment,  that  is:  analysis,  specification,  design,  coding, 
validation,  test  and  integration. 

b.  Decommission  Phase 

During  this  phase  an  assesmeit  of  the  software 
is  mace  to  determine  its  further  use,  or  to  be  replaced  in 
its  entirety.  This  may  be  due  to  completed  new  requirements 
where  it  is  considered  more  economical  to  replace  the  soft¬ 
ware  then  to  modify  the  existing  system  or  where  procurement 
of  new  hardware  dictates  a  new  software  system  be  developed. 

B.  SOFTWARE  MANAG EHE8T 

Software  management  is 
tior.  of  a  large  software 
manaatrs  of  weapon  system 
difference  between  whether 
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critical  to  one  successful  opera- 
system.  The  decisions  made  by 
software  projects  will  mean  the 
the  final  oroduct  is  mainc air.aole 


or  non-aaintainable.  Cave  (Bef.  29]  beliaves  that:  ’’Project 
failures  are  generally  the  result  of  improper  or  inexperi¬ 
enced  management  and  not  the  lack  of  technical  ability.” 
Cave  concludes  that  the  successful  development  of  large 
software  systems  can  be  achieved  in  a  consistant  manner. 

In  Cooper's  point  of  view  [Bef.  30]  a  common  stumbling 
block  of  software  project  management  has  been  that  manage¬ 
ment  would  always  seek  to  optimize  the  development  process 
in  trying  to  meet  budget  and  scaedule  constraints.  This  type 
of  approach  creates  an  initial  design  with  little  documenta¬ 
tion  resulting  in  increased  difficulty  in  maintaining  the 
software  and  a  corresponding  increase  in  overall  life  cycle 
costs. 

While  there  is  no  step  by  step  process  which  will  guar- 
entee  successful  development  of  maintainable  software,  some 
general  policies  may  be  stated  that  are  quite  helpful.  Daly 
[Bef.  31]  lists  several  items  taat  have  proved  useful  based 
cn  his  experience  in  managing  software  developments.  Table 
II  provides  a  listing  of  two  different  approaches.  Daley 
recommends  Method  1  in  order  to  produce  a  cost-effective, 
more  maintainable  software  product.  He  also  recommends  the 
aDplication  of  strict  management  objectives  to  guide 
development. 

1.  DO  D  Manage  meat  Policies 

In  December  1974  a  DOD  Software  Steering  committee 
was  established  with  a  goal  of  identifying  critical  weapon 
system  software  problems  and  to  recommend  policies  for  their 
solution. 

To  support  this  committee  the  MIT52  corporation,  in 
conjunction  with  John  Hopkins  University  [Ref.  32,33  ] 
conducted  a  study  of  weapon  system  software  management.  it 
was  concluded  that  ’’...the  major  contibuting  faotor  to 
weapon  system  problems  is  tie  lack  of  discipline  and 
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TABLE  II 

Software  Design  Methods 


Method  1 


High  level  language 

Structured  Code 

Composite  design(hierarchy 
of  small  segments) 

Parallel,  top-down,  bottom 
-up  design  all  optimally 
used 

SimoLe  data  structures  and 
work  areas  (not)  tightly 
packs  d 


Team  approach  to  design 
(egoless  programming) 

IBM's  structured  walk¬ 
through  for  reviewing 
detail  design  and  code 

Three  seoerate  tea  ms,  one 
design,  one  tests,  one 
evaluates 

Complete  set  of  hierarchy 
charts,  sequence  charts 
data  maps  ana  narratives, 
well  commented  listing 

Detailed  test  plans  for 
all  test  phases 

Prcaram  maintained  by  30?: 
senior  pro  err  a  miners 


Only  commercial 

dccua enta^ion  s  n  *5 tsl z. 6 d 

iurin a  development 

S  trio4:  ma  nacre  me  nt 
objec-ives  esta bl i shad 
to  cuiae  development 


Method  2 


Assembly  language 
Tight  lonplex  Cede 
Large  blobs  of  cods 


Bottom-up  design 


Tight,  affscient,  data 
structures  and  work  area 
every  bit  used,  no  data 
uplicatsi) 

Ons  progcaa-One  man 
concept 

No  detailed  technical 
review  of  design  or  cods 


Original  coder  tests, 
integrates  and  helps 
evaluate  his  program 

Details!  flow  charts  and 
general  narratives,  no 
consistency  listing 
with  coransnts 

No  formaL  test  plans 


Pro  ar an  maintained  ov 
inexperienced  proqra inner 
cr  technicians 

Extensive  non-ccmmer cial 
technical  nemorandun 
uenerated  and  placed  in 
Horary 

Nc  management  objectives 
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engineering  rigor  applied  to  weapon  system  acquisition 
activities.” 

The  software  nanageaent  steering  committee  incorpo¬ 
rated  this  and  other  ideas  into  a  comprehensive  plan  to 
include  policy,  practices,  procedures  and  technology  initia¬ 
tives  *  Ref.  34],  Parts  of  the  plan  are  intended  as 
supplements  to  principles  stated  in  ODD  Directives  5000.1 
and  5000.2.  The  first  maintenance  management  policy  states 
that  "Ease  of  maintenance  and  modification  will  be  a  major 
consideration  of  the  initial  design.” 

Two  techniques  are  used  to  provide  management 
control  to  weapon  system  software.  These  are  design  reviews 
and  configuration  management. 

a.  Design  Reviews 

MIL-STD- 1 521 (USAF)  annotates  and  describes  the 
requirements  for  the  following  technical  reviews  and  audits 
on  computer  programs: 

-  Systems  Requirements  Review  (SRR) 

-  Systems  Design  Review  (SDR» 

-  Preliminary  Design  Review  (?DR) 

-  Critical  Design  Review  (ZDRi 

-  Functional  Confirmation  Audit  (FCA) 

-  Physical  Configuration  Audit  (PSA) 

-  Formal  Qualification  Review  (FQR) 

A  software  maintenance  guideocck  [Ref.  35]  provides  a 
suoplement  to  SH.-STD-152 1.  It  describes  items  to  oe  taken 
info  consideration  in  order  to  optimize  toe  maintainability 
of  software.  For  sDecific  definitions  nr.  any  of  tna  aoove 
items  one  is  referred  to  standard. 
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b.  Configuration  Management 


Configuration  management  consists  of  configura¬ 
tion  identification,  control,  status  accounting  and 
auditing . 

As  part  of  the  proposed  requirements  assigned  to 
contractors  for  the  development  of  weapon  system  software, 
MIL-STD- 1679 ,  Weapon  System  Software  Development,  states: 


The  contractor  shall  establish  and  implement  the 
disciplines  of  configuration  management;  namely  configu¬ 
ration  identification,  con f igur ation  control.  and 
configuration  status  accounting.  The  contractor  shall  be 
cognizant  cf  the  requirement  for  long-term  life  cycle 
support  of  the  weapon  system  software.  The  appropriate 
degree  of  configuration  management  saall  be  applied  to 
ensure  completely  accurate  correlation  between  descrip¬ 
tive  documentation  and  the  program  in  order  to 
facilitate  post-del iverv  maintenance  by  software  support 
personnel. 


Configuration  identification  involves  specifi¬ 
cally  identifying  and  labeling  the  configuration  items  at 
selected  baselines  during  the  software  life  cycle. 
3a3elir.es  are  reference  points  or  plateaus  in  the  develop¬ 
ment  of  a  system;  a  baseline  is  formally  defined  at  the  end 
of  each  stage  in  the  system  life  cycle.  For  example  the 
functional  baseline  is  typically  the  requirements  specifica¬ 
tions  document  that  outlines,  in  terms  both  the  buyer  and 
developer  car.  understand  and  agree  to,  exactly  waat  the 
system  will  dc.  Configuration  items  are  one  individual  enti¬ 
ties  that,  together,  define  and  describe  the  baseline. 
[  39f  .  36  ] 

Configuration  control  provides  the  means  to 
manage  changes  to  the  (software)  configuration  items  ar. i 
involves  three  basic  ingredients: 

•  Documentation  (such  as  administrative  forms  and 
suooortir.  g  technical  and  administrative  material)  for 
for  me  11  v  oreoio  i  tat  i  r.q  and  definite  a  orooo  see  change 
to  a  software  system. 

•  An  organizational  body  dor  formally  evaluating  and 
acorovmg  or  ansacor ovnng  a  Droposeu  rnar.ee  to  a  soft¬ 
ware  system. 
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•  Procedures  for  controlling  the  actual 
software  system. 

Software  configuration  status  accounting  proviies  the 

mechanism  for  maintaining  a  record  of  how  the  software 

evolved  and  where  the  software  is  at  any  current  stage  of 

implementation.  Software  configuration  auditing  provides  a 

means  to  determine  how  well  the  software  product  matches  its 

associated  documentation.  [Bef.  36] 

DOD  Directive  5303.  29,  Management  of  Computer 

Resources  in  Major  Defense  Systems,  states: 

Defense  system  computer  resources,  including  both 
computer  hardware  ana  compute r  software  will  be  speci¬ 
fied  and  created  as  configuration  items. 

The  primary  objective  of  software  configuration 
management  is  the  effective  management  of  a  software 
system's  life  cycle  and  its  a  volvia  g  configuration. 
Configuration  is  the  final  form,  arrangement  or  design  of 
the  software  fRef.  36],  The  importance  of  configuration 
management  is  that  it  gives  one  the  ability  to  manage  change 
during  the  development  process.  If  a  program  maintenance 
manual  is  being  designed  in  conjunction  with  and  as  a  part 
of  the  software  system  development,  then  it  should  be  placed 
under  the  discipline  of  configuration  management.  Changes 
in  the  iesiar  and  contents  of  the  maintenance  manual  can  be 
matched  or  directly  linked  to  changes  in  the  software 
system.  This  is  the  intent  of  ODD  Directive  5030.29. 

2.  DOD  Directives  and  -Standards 

Policies  and  procedures  for  acquisition  of  weaccr. 
system  software  are  different  in  most  respect?  from  these 
used  for  prccurring  automated  data  processing  equipment 
( A D ? E)  .  The  distinction  made  between  these  two  categories  of 
automated  systems  is  a  direct  result  of  '-he  1  965  "Brooks 
Art"  (Public  Law  99-  3  06,  u0,  J.5.C.  7  5  9). 


The  Office  of  Management  an  Budget  (OMB)  and  the 
General  Services  Administration  (GSA)  adninister  the  Brooks 
Act  guidelines.  ADP2  is  controlled  by  this  Act  and  falls 
under  the  cognizance  of  tie  Assistant  Secretary  of 
Def ense(Controller) .  Weapon  system  software,  on  the  other 
hand,  is  excluded  fronm  the  provisions  of  this  Act  and  fall 
under  the  jurisdiction  of  the  Office  of  tie  Under  Secretary 
of  Defense  for  Research  and  Engineering. 

There  is  no  centralized  source  of  guidance  with 
respect  to  weapon  system  software  maintenance  for  DOD 
or gainza tions  to  follow.  There  are  many  directives,  regula¬ 
tions,  specifications  and  standards  that  impact  on  weapon 
system  software  to  varying  degrees.  The  Dost  important  ones 
are  described  here. 

a.  Weapons  Standard  W3  8505 

WS  8506  is  considered  to  be  a  comprehensive  and 
very  good  specification  for  the  documention  of  program 
development,  particularly  in  view  of  its  early  publication 
date  (1971).  one  of  its  strong  points  is: 

A  strategy  for  making  each  level  of  documentation 
responsive  to  the  next  uoner  level  (suborocrraa  design 
under  program  design)  which  represents  foresight  in  the 
use  of  too-cown  design  Drior  to  the  tine  this  term  was 
in  vogue  [Ref.  15]. 

It  dees  not  include  such  programming  techniques  as  struc¬ 
tured  programming,  but  this  technique  was  not  developed  at 
the  time  of  its  publication. 

Its  weaknesses  include  a  iac<  of  change  proce¬ 
dures,  documentation  standards  for  diagrams  (such  as 
Hierarchy  Input/Output  or  HIP9)  and  regression  testing 


b.  MIL-STD-4  83  (USAF) 
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MIL-STD-483  (USAP)  'Configuration  Management  for 
Systems,  Equipment,  Munitions,  and  ComputerPrograms,"  1  June 
1971,  defines  the  entire  spent  rum  of  artivi-.es  associated 
with  controlling  changes  (a  critical  need  for  maintenance 
work)  to  computer  programs. 

c.  MIL-S-527  79  (AD) 

MIL-S-52779  (AD),  "Software  Juality  Assurance 
froqram  Requirements,"  5  April  1974,  requires  that  a  Juality 
Assurance  Program  (QAP)  be  implemented  specifically  for  the 
development  of  computer  progress  and  related  documentation. 
Even  though  this  standard  is  concerned  with  the  development 
phase,  it  is  important  because  it  can  directly  affect  the 
quality  of  software  documentation. 

d.  SECNAVINST  3560.  1 

SECNAVINST  3560.  1,  "Department  of  the  Navy 
Tactical  Digital  Systems  Documentation  Standards,"  3  August 
197a,  identifies,  names  and  describes  that  set  of  documents 
necessary  to  supprt  both  the  development  and  maintenance  of 
tactical  software.  A  review  of  3560.1  was  conducted  to 
determine  how  well  this  standard  supports  software  mainte¬ 
nance  activity  (Ref.  37],  As  noted  by  this  review  there  are 
some  positive  and  negative  aspects  to  tie  standard.  Some 
positive  aspects  include: 

-  ADtlicable  document  statements. 

-  Resource  budgets  (time, space)  . 

-  Numerous  examples. 

-  Content  check  lists. 

-  Interface  descriptions. 

-  Test  coverage. 

-  Detailed  Table  of  Contents  for  each  s o e cif icat ion . 


The  deficiencies  of  the  standard  include  a  lack 
of  requirements  for  the  subject  of  traceability,  a  need  for 
increased  emphasis  on  validation,  and  the  use  of  inconsis- 
tant  or  nor.-defined  terminology.  The  review  indicates  the 
standard  seems  more  orientated  towards  software  development 
then  to  softwre  maintenance.  The  review  also  notes  the  stan¬ 
dard's  strong  orientation  towards  the  Savy's  tactical  data 
system.  Scr.eidewin  d,  [Bef.  37],  recommends  "...a  more 
general  orientation  might  be  preferable  to  achieve  a  wider 
applicability  to  a  variety  of  software  systems.” 

e.  DCD  DIRECTIVE  5300.  29 

DOD  DIRECTIVE  5000.2  9,  "Management  of  Computer 
Resources  in  Major  Defense  Systems,”  26  April  1976,  estab¬ 
lishes  DOD  policy  for  the  management  and  control  of  computer 
resources  during  system  acquisition.  1  attainability  of 
software  is  called  out  as  a  major  consideration  during  the 
initial  design.  It  also  directs  that  support  items  required 
for  cost  effective  maintenance  be  specified  as  deliverable 
items.  Documentation  is  listed  and  defined  as  a  support 
item. 

f.  MIL-3TD-1 521  (USAFl 

MIL- STD- 1  52 1  (USAFi  ,  "Technical  Reviews  and 
Audits  for  System,  Equipment  and  Computer  Programs,”  1  June 
1976,  prescribes  the  requirements  for  tie  conduct  of  tech¬ 
nical  reviews  and  audits  in  conjunction  with  the  documents 
defined  in  MlL-STD-h  8  3.  Direction  is  provided  concerning  the 
review  and  audit  of  computer  program  configuration  items  and 
their  associated  documentation.  Each  type  of  review  or  audit 
is  described  in  an  appendix  to  the  standard  and  can  serve  as 
a  basis  for  checking  compliance  with  maintainability 
requirements.  The  documentation  discussed  here  is  related 
more  toward  system  design  reviews  then  towards  the 
documentation  of  program  listings. 
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g.  DODINST  5000.31 


DOD  Instruction  5030.31,  "Interim  List  of  DOD 
Approved  High  Order  Programing  Languages  (H3L),"  24 

November  1976,  specifies  which  HOL’s  are  approved  foe  use  in 
conjunction  with  DOD  Directive  50  00.29.  Although  this 
instruction  allows  for  certain  exceptions,  it  attempts  to 
reduce  the  proliferation  of  HOL’s  in  defense  systems  by 
limiting  new  development  to  six  approved  languages:  CHS-2, 
SPL-1,  I ACPOL,  JOVIAL,  COBOL,  and  FORTRAN.  Its  major  impact 
is  in  the  standardization  of  compilers  and  in  preventing 
each  DoD  activity  from  developing  its  own  unique  programming 
lang  uage . 

h.  MIL-STD- 1 679  (NAV  Y> 

MI L -STD- 1  679  (NAVY)  ,  "Weapon  System  Software 
Development,"  1  December  1973,  establishes  uniform  require¬ 
ments  for  the  development  of  weapon  system  software  within 
DOD.  Strict  adherence  to  the  provisions  of  this  standard 
will  help  ensure  that  the  tactical  software  so  developed 
will  be  improved  over  current  versions  of  tactical  software. 
MIL-STD- 1679  includes  developments  in  programming  tech¬ 
nology,  and  management  such  as  structured  programming  and 
design  walkthroughs,  which  have  occurad  since  the  release  of 
WS  8506.  It  stipulates  the  use  of  higa  order  languages  and 
specifies  the  use  of  configuration  management  for  corre¬ 
lating  documentation  with  the  program  for  maintenance 
purposes.  [Ref.  15] 


III.  TECHNIQUES  TO  SUPPOHJ  SOFTWARE  DO COM ENT AJI3 S 
A.  STRUCT OR ED  PROGRA  HMIHG 

There  are  several  definitions  and  goals  of  structured 
programming.  Some  of  these  goals  relate  to  the  design  and 
testing  of  large  software  systems.  One  particualr  goal  of 
structured  programming  is  to  organize  and  discipline  the 
program  design  and  coding  process  in  order  to  reduce  logic 
type  errors  (Ref.  38].  It  is  generally  accepted  that  the 
goals  of  structured  programming  include  those  of  software 
engineering.  In  particular  these  goals  are:  modifiability, 
efficiency,  reliability,  aid  understandibility  of  the 
program  code  (Ref.  39], 

What  must  be  shown  is  how  structured  programming 
supports  documentation.  This  is  not  easy  to  do  because 
structured  programming  is  not  a  universal  and  well  defined 
concept.  It  is  defined  in  many  places,  [Ref.  39,40,^2],  but 
not  always  consist  ant ly .  However,  its  essence  is  fairly  well 
understood.  It  is  the  practice  of  of  programming  using  a 
limited  out  sufficient  set  of  control  constructs  Figures  3.1 
and  3.2  illustrate  the  five  basic  control  constructs  as 
required  by  HIL-3TD- 1 679. 

Myers  (Ref.  18]  provides  a  List  of  sever,  basic  elements 
of  a  structured  program  which  should  oe  aoolied  to  help 
reduce  program  complexity  and  promote  cuarity  or  thought  by 
the  programmer. 

•  The  cede  is  constructed  from  sequences  of  basic 
elements. 

•  Use  of  the  GQTQ  statement  is  avoided  wn^r.ever  possible. 

•  The  code  is  written  in  an  acceotable  stvle  (e.  g.  use 
meaningful  variable  names,  avoid  statement  .ables, 
avoaa  language  tricks). 

•  The  code  is  orocerlv  indented  on  tie  distant  so  that 
breaks  in  execution'  sequence  can  oe  easily'  followed 
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to  n 
-fc-*  u 


(e.  g.  a  DO  statement  can  be  easily  matched  with  the 
ENDDO  statement  ending  the  loop)  . 

•  There  is  only  one  point  of  entry  and  one  point  of  exit 
m  the  code  for  each  module. 

•  The  code  is.  .physically  segmented  on  the  listing  to 
enhance  readibilty.  The  executable  statements  for  a 
module  should  fit  on  a  single  page  of  the  listing. 

•  The  code  represents  a  simple  and  straightforward  solu¬ 
tion  to  the  problem. 

Figure  3.3  provides  an  example  of  structured  and  unstruc¬ 
tured  coding.  A  structured  program  is  structured  in  two 
different  ways.  First,  it  is  structured  with  regard  to  flow 
of  control  and  execution  of  the  program.  Second,  it  is 
physically  structured  by  the  use  of  indentation. 

Another  way  of  viewing  structured  programming  is  to  see 
it  as  those  attributes  of  a  program  that  contribute  to  the 
readibilty  of  its  form.  For  example  consider  the  develop¬ 
ment  of  a  file  management  system.  Obviously  one  required 
function  of  such  a  system  would  be  the  capability  to  search 
for  a  given  file  identified  by  a  specific  name.  Figure  3.4 
illustrates  such  a  function  as  coded  in  the  recently  devel¬ 
oped  DOD  high  order  language  A 0 A  (see  rRaf.  44]  for  details 
on  the  ADA  language).  As  can  be  seen  in  Figure  3.4  struc¬ 
tured  programming  makes  for  a  more  readable  and  discernible 
sequence  of  code.  The  main  tenants  of  structured  programming 
are  displayed,  that  is;  hieraroiic  relatinnships  between  the 
lines  of  cede,  a  consist  ant  indentation  policy,  and 
begin-ena  groupings  which  make  it  easier  to  follow  the 
proaram  flow.  Comments  are  used  extensivly  to  introduce 
each  new  module  and  structure. 

The  results  of  structured  programming  are  readily  appa¬ 
rent  with  easy  to  read  cede  and  easy  to  follow  logic  flow. 
Functions  and  procedures  are  confined  to  discrete  areas  ir. 
the  program  listing.  The  objective  is  to  nake  the  code,  in  a 
very  meaningful  and  useful  way,  self- documenting,  thus 
reducing  the  need  for  external  documents  describing  the 
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Do-UntiL 


DO  UNTIL 


Case 


Figure  3.2  Basic  Control  Constructs. 
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UNS£HUCI2jjED 

3 TRUQT3RED 

IF  p  GOTO  label  g 

1  IF  p  THEN 

IF  w  GOfO  label  m 

A  function 

L  function 

B  function 

GOTO  label  k 

2 

IF  7  THEN 

label 

m 

M  function 

3  IF  t  THEN 

GOTO  label  k 

G  function 

label 

q 

IF  g  GOTO  label  t 

4  DOWHILE  a 

A  function 

H  function 

B  function 

4  ENDDO 

C  function 

I  function 

label 

r 

IF  NOT  r  GOTO  label 

5 

3  (ELSE) 

D  function 

3  ENDIF 

GOTO  label  r 

2 

ELSE 

label 

s 

IF  s  GOTO  label  f 

Z  function 

2  function 

3  DOWHILE  r 

label 

V 

IF  NOT  v  GOTO  label 

< 

D  function 

J  function 

3  ENDDO 

label 

k 

K  function 

3  IF  s  THEN 

END  function 

F  function 

label 

f 

F  function 

3  ELSE 

GOTO  label  v 

E  function 

label 

IF  t  GOTO  label  a 

3  ENDIF 

A  function 

2 

ENDIF 

B  function 

2 

IF  v  THEN 

GOTO  label  w 

J  function 

label 

a 

A  function 

2 

(ELSE) 

B  function 

2 

ENDIF 

G  function 

1  ELSE 

label 

u 

IF  NOT  u  GOTO  label 

2 

IF  w  THEN 

H  function 

M  function 

GOTO  label  u 

2 

ELSE 

label 

w 

IF  HOT  t  GOTO  label 

y 

L  function 

I  function 

2 

SNDIF 

label 

y 

IF  NOT  V  GOTO  label 

!c 

1  2 

NDI? 

J  function 

K 

function 

GOTO  label  k 

2 

ND  function 

Figure  3.3  Structured  vs.  Unstructured  Coding. 

:ode.  This  has  an  effect  on  the  design  of  the  document 
:alled  the  Pregram  Maintenance  Manual  and  will  be  discussed 
.n  detail  in  Chapter  IV. 
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function  SEARCH  (F 
FILE  INDEX  is 
begin 

—  Look  for  the 

—  specified  fi 

—  position 

for  I  in  FI 
—  Search  t 

—  last 

if  FI 
—  Ch 

—  13 

an 
an 
re 
end  i 
end  loop; 
raise  BAD  F 
—  Raise  an 

—  is  not  f 
end  SEARCH; 


ILE_NAME ;  KE  Y_TY  PE)  return 

specified  Key  record  in  the 
le,  returning  the  index  of  its 

LE  INDEX' Ft  RST.  .  FILE  INDEX'LASI  loop 
he'whole  data  base,  from  first  to 

LE  MAP(I)  /=  NULL 

ecx  data  base  for  a  null  or  a 

tch 

d  then  FILS  MAP(I)  =  FILE  NAME 
d  then  FILE~KEY(I)  =  KEY  TYPE  then 
turn  (I)  ; 
f; 

HE; 

exception  if  the  desired  record 
ound 


Figure  3.4  File  Search  Function. 

B.  MODULARIZATION 

Modules  are  the  building  blocks  o£  software.  Soon 
nodular  programming  usually  requires  that  external  inter¬ 
faces,  such  as  inp ut/output ,  be  isolated  into  separate 
modules.  Modular  programming  itself  is  the  practice  of 
implementing  software  in  small,  functionally  orientated 
Dieces.  These  pieces  are  usually  implemented  as  subroutines, 
functions  or  clusters  of  functions.  Each  module  is  devoted 
to  cr.e  or  more  tasks  related  to  a  function;  the  module  may 
be  accessed  from  one  or  several  places  in  the  software 
system. 

Modularity  is  often  defined  in  :  er  ms  of  properties  poss¬ 
essed  by  "modular''  systems. 


A  program  is  modular  if  it  is  written  in  m  a  n  v  relatively 
independent  parts  or  modules  which  have  well  defined 
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interfaces  such  that  each  module  makes  no  assumptions 
about  the  operation  of  other  modules  except  what  is 
contained  in  the  interface  specifications. 

Modularization  consists  .of  dividing  a  program  into 
subprograms  (modules)  which  can  be  comoixea  separately, 
but  which  have  connections  with  other  modules.../)  defi¬ 
nition  of  '•good”  modularity  must  emphasize  the 
requirement  that  modules  be  as  disjoint  as  possible. 

Modular  .programming  is  the  organizing  of  a  complete 
program  into  a  number  of  email  units. ..  where  there  is  a 
set  of  rules  which  controls  the  characteristics  of  these 
events . 

Modularity  ce^ls  with  how  the  structure  ? f  an  object  can 
make  the  attainment  of  some  purpose  easier.  Modularity 
is  purposeful  structuring  [Ref.  33]. 

There  is  a  trend  towards  defining  modules  in  terms  of  the 
number  of  lines  of  code  they  contain.  Programming  standards 
frequently  contain  a  somewhat  negative  approach  such  as 
". . . modules  shall  contain  less  than  X  lines  of  code."  Some 
authors  feel  that  the  size  aspect  is  not  as  important  to  a 
module  as  its  functional  aspect.  Ir.  other  words  a  small 
complex  module  may  be  more  difficult  to  understand  than  a 
large  well  structured  module.  However,  the  majority  still 
favor  limiting  module  size,  when  possible,  to  less  than  100 
lines  of  code  in  order  to  maintain  modules  as  "discrete" 
entities  and  J-o  aid  comprehension  [Ref.  33,40], 

There  are  many  advantages  to  using  modules.  Parnas 
[Ref.  24]  argues  that  the  most  important  aspect  of  modulari¬ 
zation  is  the  ability  to  anticipate  and  design  for  changes. 
If  the  function  of  a  module  changes,  that  module  alone  has 
to  change.  If  the  need  for  a  function  arises  during  the 
design  ohase,  a  module  with  tais  function  can  be  invoked  at 
the  pcint  cf  need.  If  an  error  in  the  pro. ram  is  found,  the 
probability  is  that  its  correct  ion  will  be  limited  to  one 
module.  Once  a  module  has  been  tested,  and  can  be  compiled 
separately,  it  can  be  reliably  used  in  different  places  in 
the  program.  fRef.  4  1] 


Since  modularization  makes  the  structure  of  a  program 
easier  to  understand  while  localizing  functions  and 
processes,  the  need  for  external  documentation  is  again 
reduced. 

As  a  final  note,  there  has  to  be  a  distinction  made 
between  modualrity  and  structured  programing. 


This  iistinction  is  necessary  because  program  structure 
is  a  relatively  meaningless  concept  in" some  programmina 
languages,  such  as  plain  vanilla  assembly  language  (as 
opposed  to  assembler  enhance!  with  strong  macro  capa¬ 
bility).  In  contrast,  modularity  is  usable  in  all 
domains.  Thus,  the  line  between  modularity  and  structure 
may  be  a  tenuous  one  tc  walk,  but  it  is  an  important 
one.  Note  that  good  modules  may  or  may  not  possess  good 
program  structure  and  that  bad  modules  may  also  possess 
pood  program  structure.  The  two  subjects  are  discecnable 


C.  DATA  STRUCTURE 

In  seme  programming  languages  there  are  at  least  two 
ways  of  working  with  a  string  of  bits  or  characters.  Dne  way 
is  tc  declare  the  string  as  parr  of  a  structure  (Figure  3.5) 
and  then  manipulate  the  string  oy  name: 

OTHER  STEINS  =  CHARACTER  SIRING 


Structure  DATA  STRUCTURE;  begin  I 

item  CHARACTER  SIRING  5  characters;  I 

item  OTHER  VARIABLE  32  oits;  I 

end  Structure;  ~  I 


Fiaure  3.5 


Example  of  a  Data  Structure. 


A  second  method  is  to  use  a  byte  manipulating  function  to 
define  the  desired  string  at  every  point  of  usage  ir.  the 
program: 

OTHER_STRIN  G  =  BYTE (IB AR AD TER_S T RI NG, 5) ; 

Suppose  the  character  string  named  OTHER_3TRING  is  utilized 
100  times  ir.  the  program.  I.n  order  to  change  the  string 
format  using  the  first  method  (Figure  3.5*  ,  only  one  easily 
identified  line  of  code  has  to  change.  In  the  second  case 
there  are  100  lines  to  change  throughout  the  program. 

Languages  may  or  may  net  support  such  data  structuring. 
COBOL  and  PL/I  provide  elabor_.e  data  structures  for  format¬ 
ting  report  data  for  printout.  _  addition  such  changes  as 
stripping  off  leading  zeros,  inserting  a  decimal  point, 
adding  check  protect  characters,  and  inserting  a  leading 
dollar  sign  are  easily  accomplished.  At  the  other  extreme 
FORTRAN  and  BASIC  offer  no  data  structure  capability  beyond 
the  array  [Ref.  43]. 

Data  structure  impacts  the  areas  cf  software  design  and 
software  maintenance.  One  mstiodology,  called  the  Jackson 
method  *  Ref.  45],  stresses  designing  the  program  structure 
by  first  locking  at  the  data  structures.  According  to 
Jackson,  an  algorithmic  structure  is  highly  related  to  data 
structure;  programs  that  obey  data  structure  design  will 
have  a  more  maintainable  program  structure  as  well. 
Obviously  different  application  areas  have  different  levels 
of  need  for  data  structure  orientation. 

Or.e  of  the  r.oticabie  effects  of  large  software  systems 
is  that  algorithms  end  up  transforming  one  data  structure 
into  another  data  structure.  This  results  in  what  Jackson 
terms  a  "structure  clash."  The  reason  for  this  cccurir.g  is 
commonly  a  proliferation  cf  unnecessary  code,  lack  or  struc¬ 
tured  programming  coals,  or  lack  of  design.  Sometimes  the 
"clash"  is  a  result  of  maintenance,  corrective  ar.d 
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enhancemer t,  where  the  changes  have  aided  information  or 
changed  the  data  structure  to  meet  the  current  need.  Two 
solutions  have  been  proposed  in  this  area.  Grouping  or 
"clustering”  of  data  and  abstract  data  typing  [Ref.  43,  49]. 

Where  a  set  of  data  declarations  interrelate,  either  by 
function  or  by  context,  they  should  be  grouped  together  for 
ease  of  understanding  and  modification  into  one  block.  This 
is  the  " clustering"  concept.  If  a  change  is  needed  it  can  be 
isolated  into  one  block.  Only  those  modules  which  use  than 
block  of  data  need  be  recompiled. 

With  the  concept  of  abstract  data  typing,  such  as  used 
by  PASCAL  and  ADA,  [Ref.  44]  all  data  must  be  explicitly 
declared  to  be  of  a  particular  type.  Certain  types  are 
defined  in  the  language,  but  these  must  be  supplemented  by 
programmer-defined  types.  Associated  with  a  type  is  a  set  of 


ype  RECORD  FORMAT  1  is 
record-  ~ 

EMPLOYES  NAME:  array(1..30l  of  CHARACTER ; 
EMPLOY  EE-?.  ATE:  float; 

EMPLOY  EE-HOUP.S  :  integer  range  0..99; 

'ILE1  RECORD:  RECORD  FORMAT  1 


Figure  3.6  Example  of  an  ADA  Data  Structure. 

legitimate  values  which  objects  of  a  type  may  assume  ar.d  a 
set  cf  operations  which  may  oe  performed  on  that  type. 
Figures  3.5  ar.d  3.6  show  examples  of  ADA  data  structures. 

This  kind  of  typing  has  three  charact eristics:  (1)  ‘•he 
properties  of  a  type  are  defined  centrally  at  the  *yps 
declaration,  ar.d  if  they  change  they  need  only  be  charged  in 
one  plac * ;  (2)  only  the  abstract  properries  of  a  type  need 
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be  known  to  reference  data  of  chat  type,  with  implementation 
details  "hidden"  in  the  declaration;  #  and  (3)  strong  type 
matching  may  be  enforced  by  the  compiler,  eliminating  type 
mismatch  errors  as  a  reliability/maiitainability  issue 

[Ref.  43,44]. 

As  a  final  consideration,  it  is  always  important  to  name 
data  effectively.  Meaningful  names  are  always  preferable. 
EMPLOyEE_NAME  conveys  far  more  information  about  the  data 
value  then  EMPNAM.  This  supports  the  goal  of  readability  and 
the  ultimate  goal  of  having  the  program  be  as  self 
documenting  as  possible. 

D.  DATA  COMMDNICATION 

There  are  two  basic  types  of  data  conn  an ication,  intra¬ 
program  and  inter-program.  Intra-program  data  communication 
is  essentially  communication  between  modules.  This  can  be 
accomplished  cv  paramenter  lists,  global  (or  common!  data 
and  a  recent  concept  called  a  data  "cluster".  A  cluster  is 
where  a  constrained  "  semiglobal '  data  bass  is  shared  among  a 
limited  number  of  processes  or  functions.  "Ref.  42,43,44  ] 

A  Da ra me- e r  list  identifies  only  those  data  items  and 
formal  parameters  used  by  each  individual  module.  The 
preferred  method  of  intra-program  communication  is  by  the 
use  of  a  parameter  list  [Ref.  43].  The  main  advantage 
gained  is  that  all  data  used  by  the  module  are  identified 
and  isolated.  It  is  not  possible  for  the  module  to  have  a 
surprise  effect  on  the  cede  which  invokes  the  module. 

Glcoal  variables  are  used  for  large  guar. titles  of  data 

o  specify  suci  a  lar  parameter 


w.-.en  i-  is  net  convenient 
list  at  each  Doin.t  of  cai 


oacameter 


lost  authors  recommend  minim¬ 


izing  tie  use  of  global  data  for  good  modular  and  structured 
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for  limited  use  is  that  a  module  may 
whose  or  ideal  value  was  critical  to 


the  calling  environment.  This  may  lead  to  undesirable  and 
(  untracable  side  effects.  [Ref.  40,42] 

A  side  effect  is  cne  brought  about  other  than  via  a 
parameter  mechanism.  It  is  generally  considered  rather 
undesirable  to  write  subproarams,  especially  functions, 
which. h^ve  side  effects.  However,  some  side  effects  are 
beneficial.  Any  subprogram  which  performs  input-output 
I  has  a  side  effect  on  the  file;  a  function  delivering 

successive  numbers  of  a  segueace  of  random  numbers  only 
works  because  of  its  side  effects:  if  one  needs  to  count 
how  many  times  a  function  is  called  then  we  use  a  side 
effect;,  and  so  on.  Care  must  be  taken  whan  using  func¬ 
tions  with  side  effects  that  the  function  does  not  cause 
errors  in  ether  sections  of  tie  program.  [Ref.  44] 

[ 

The  cluster  concept  is  an  attempt  to  fulfill  the  need 
for  global  variables.  A  data  oase  and  its  family  of  manipu¬ 
lating  procedures  is  isolated  from  the  cast  of  the  program. 
A  program  needing  some  or  all  of  of  the  clustered  data  must 
explicitly  import  it.  The  cluster  itself  can  distinguish 
between  data  and  procedures  which  may  be  exported  or  not. 
The  side  effect  problem  is  at  least  isolated  and  bounded. 
[Ref.  40,42] 

Inter- progra m  data  communication  is  provided  either  by 
passing  data  flags  and  blocks  through  ai  operating  system 
communication  area,  or  by  passing  larger  volumes  of  informa¬ 
tion  on  files.  The  UNIX  concept  of  "pipes"  in  which 
predefined  files  are  automatically  passed  from  cne  program 
to  the  next  is  an  example  of  this  type  of  data 
communication.  [Ref.  47] 

The  proper  use  of  data  cona unication  clarifies  program 
flow  and  tracabi lit y  of  processes.  This,  of  course,  supports 
the  maintenance  programmer's  task  ir.  the  correction  of 
program  errors  and  in  his  understanding  of  the  program's 
document  a  tier.. 
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High  order  languages  are  tiiose  computer  languages  which 
are  essentially  machine  (hardware)  independent.  This  is  in 
contrast  to  assembly  languages  that  were  designed  for  a 
particular  hardware  architecture.  For  example,  the  INTEL 
8080  assembly  instruction  set  will  not  work  at  all  on  a 
Motorola  6800  based  machine.  In  contrast  a  standard  FORTRAN 
program  can  easily  be  used  on  any  computer  with  an  appro- 
piate  FORTRAN  compiler. 

Higa  order  languages  tend  to  support  the  concepts  just 
discussed  (structured  programming,  modularity,  data  struc¬ 
ture,  etc.)  to  varying  degrees.  FORTRAN  offers  modularity, 
but  is  limited  for  program  structuring  and  has  almost  no 
capabilty  for  data  structuring.  COBOL  has  excellent,  robust 
capabilities  for  data  structures.  Other  languages  have  their 
strong  and  weak  points.  [Ref.  43]  Examples  of  good  SOL  code 
may  be  found  in  several  references  "Ref.  13,42]. 

Documentation  is  supported  by  High  Order  languages 
(HOL's)  if  the  language  is  readable.  FORTRAN  is  limited  in 
this  respect  because  of  its  six  character  limit  on  data  and 
variable  names.  Some  HOL's,  APL  for  example,  provide  no 
readabilty  at  ail.  APL  is  very  difficult  to  understand  after 
it  is  written  down,  even  by  the  person  who  designed  the 


program. 

ADA,  the  new  programming 
Department  of  Defense,  promis 
for  just  about  all  the  major 
pies.  ADA  is  a  large  language 
•different  issues.  Some  of  the  < 
Table  III  [Ref.  44  ]. 

The  overall  objective  cf  ta 
provide  one  standardized  langu 
embedded  systems.  This  can 


language  developed  by  the 
s  to  offer  the  best  support 
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TABLE  Eli 
Key  Goals  of  ADA 


READABILITY 

It  is  recoanized  that  professional  programs  are  read 
mere  often  then  they  are  written.  It  is  important, 
therefore,  to  avoid  an  over-terse  notation  such  as 
APL. 

STRONG  TYPING 

This  insures  that  each  object  has  a  clearly  define! 
set  of  values  and  prevents  confusion  between  logically 
distinct  concepts.  As  a  consequence  many  errors  are 
detected  by  the  compiler  which  in  other  languages 
would  have  led  to  an  executable  but  incorrect  program. 

PBOGR  AMMING-IN-THE-LA  RGE 

Mechanisms  for  encapsulation,  seoerate  compilation, 
and  library  management  are  necessary  for  the  writing 
of  portable  and  maintainable  programs  of  any  size. 

EXCEPTION  HANDLING 

It  is  a  fact  of  life  that  programs  of  consequence 
are  rarely  correct.  It  is  necessary  tc  provide  a 
means  whereby  a  program  can  be  constructed  in  a 
layered  and  partitioned  way  so  that  consequences 
of  errors  in  one  part  can  be  contained. 

DATA  ABSTRACTION 

Extra  portability  and  maintainability  can  be  obtained 
if  the  details  of  the  representation  of  data  can  be 
IceDt  seoerate  from  the  specification  of  the  logical 
operations  on  the  data. 

1ASKI MG 

For  many  applications  it  is  Important  chat  the 
program  be  conceived  as  a  series  of  oarallel 
activities  rather  than  just  as  a  single  sequence 
of  actions.  Building  appreciate  facilities  into  a 
iancaage  ether  than  adding  them  on  via  calls  to  an 
operatma  system  crives  better  portability  and 
reliability. 

££2!£a££  211  22s 

In  aar.v  cases  the  logic  of  oart  of  a  crogram  is 
independent  of  the  types  of  values  bsinc  manipulated. 

A  mechanism  is  therefore  necessary  for  the  creation 
of  related  Dieces  of  proaraoi  from  a  siacLe  template. 
This  is  particularly  useful  for  the  creation  of 
libraries. 
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benefits  by  reducing  the  number  of  different  types  of  compi¬ 
lers  needed.  It  also  promotes  familiarity  by  programmers  and 
maintenance  programmers.  Improved  program  clarity  and  read¬ 
ability  should  also  simplify  the  documentation.  [Ref.  46] 


P.  THE  PROGRAM  LISTIHG 


If  the  overall  goal  is  to  reduce  the  quantity  and  cost 
of  documentation  and  improve  its  quality  and  usefulness  to 
the  maintenance  programmer,  then  it  is  highly  desirable  that 
programs  be  made  as  self-docuae  nting  as  possible.  In  this 
manner  one  can  subst ant ially  reduce  the  necessity  to  main¬ 
tain  multiple  forms  of  documentation  representing  the  same 
logic.  Many  authors  advocate  such  an  approach  through 
structured,  well  commented  program  listings.  Myers  [Ref.  18] 
s  t  a  t  es : 


Since  we  already  have  the  code,  why  not  let  it  serve  as 
the  logic  documentation?...'  additional  documentation 
such  as  a  flowchart  would  be  undesirable  because  it 
would  be  redundant  with  the  code.  Redundancy  in  any  type 
of  documentation  should  be  avoided  because  it  increases 
the  cnances  of  conflicts.  Furthermore,  unless  care  is 
taken  to  update  the  documentation  (wnich  is  more  diffi¬ 
cult  if  the  logic  documentation  is  pnysically  seD-rated 
from  the  cede),  redundent  documentation  often  becomes 
totally  useless  after  the  code  is  modified  a  few  times. 


glass  [Ref.  43]  also  agrees  with  this  point  of  view  stating: 


The  documents,  when  they  do  exist,  are  generally  written 
to  conform  a  se  per  at  e  set  of  requirements  which 

soecifv  what  the  software  documentation  is  to  contain. 
All  too  frequent! v,  these  reuu ir am si r s  provide  for 
irrelevent  or  useless  information  that  the  maintain” 
really  needs.  So,  in  a  real. sense,  the, document,  which 
is  suo  do  sec  to  oe  a  clanr  via  a  oiece  or  materia*,  end¬ 
up  obscuring  the  needed  information. 

Because  documentation  is  seoerats  from  the  software 
product  itself,  it  is  also"  frequently  out  of  date, 
ideally,  the  document  would  oe  a  perfect  reflection  of 
the  program.  In  actual  fact,  this  is  rarely,  if  ever, 
true.  The  documentation  can  therfore  he  misleading.  *hc 
in  their  right  mind  would  attempt  to  ma<e  cor r ec_i r n s  to 
a  nregraa  after  reading  on iv  the  prooram  documentation 
and  not  the  list  mo? 
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This  author  recommends  the  heresy  chat  the  listing  be 
the  place  where  post  software  documentation ,  is  placed. 
Nearly  every  requirement  for  documentation  describing  a 
program  can  be  met  and  in  fact  exceeded  by  requiring  the 
same  information  in  the  listing. 

DOD,  in  general,  supports  this  point  of  view  and  gives 
explicit  direction  for  what  constitutes  a  well  commented 
program  listing  in  MII.-STD-157  9.  However,  MIL-srD-1679, 
SECNAVINST  3560.1  and  other  directives  require  extensive, 
detailed,  external  documentation  (i.e.,  other  than  the 
program  listing)  to  be  produced.  One  vaLid  reason  for  this 
requirement  is  the  need  for  extensive  design  reviews 
required  by  configuration  management  tecnniques.  A  second 
reason  is  that,  until  the  Bi.d-1970'3  and  the  advent  of 
sofware  engineering  techniques  as  discussed  in  this  chapter, 
the  program  listing  did  net  convey  a  great  deal  of  informa¬ 
tion.  A  large  amount  of  English  text  was  needed  to  explain 
the  design  and  structure  of  tha  software  and  its  associated 
data  bases.  Even  Glass  admits  that  some  external  documenta¬ 
tion  will  always  be  required  to  give  an  overview  of  the 
structure  and  the  software's  design  history  [Ref.  43]. 

This  "external”  documentation  is  aimed  at  specific 
users.  Operator's  Manuals  are  meant  to  be  read  by  operators. 
Soecificat iens  are  meant  to  be  read  by  noth  customers  (to 
give  theta  the  ability  to  determine  that  the  problem  being 
solved  is  the  one  they  want  solved!  and  designers.  Test 
documents  are  meant  to  be  read  by  customers,  to  determine 
that  proper  reliability  tecnniques  are  employed,  and 
testers.  The  main  problem  associated  with  external  documen¬ 
tation  is  that  it  frequently  becomes  inaccurate  and  outdated 
as  maintenance  programmers  ma  Ice  changes  to  the  program  code. 
For  this  reason  maintenance  programmers  tend  to  relay  more 
ar.d  more  on  the  program  listing  as  the  software  system  gcts 
cider. 
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The  listing  is.  of  necessity,  accurate, 
program  in  all  real  senses  of  the  wor 
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is  complete.  Thus  the 
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tion  will  be  also.  In  addition,  the  ex 
listing  will  also  likely  to  be  readabl 
taroet  audience,  a  programme p.  They 
place  where  he  needs  most  to  find  them, 
completeness  attributes  of  the  listing 
apply  as  well  to  the  document  a tion.  >  R 


since  it  is  the 
i.  For  the  same 
aly  accurate  and 
in  today's  tech- 
ing...If  the  code 
at  the  docuaenta- 
planations  in  the 
e  by  the  intended 
will  also  be  in 
The  accuracy  and 
will  also  tend  to 
ef.  43] 


The  main  line  of  thought  being  developed  is  that  recent 
trends  in  programming  technology,  as  presented  in  this 
chapter,  have  shifted  the  emphasis  of  programming  documenta¬ 
tion  from  "external"  documents  to  the  program  listing 
itself.  A  greater  detail  and  quantity  of  information  about 
the  program  is  now  directly  a/aiiable  to  the  maintenance 
programmer.  This  has  a  significant  impact  on  the  way  one 
should  design  documentation  as  a  whole.  Chapter  IV  will 
discuss  this  point  of  view  as  it  applies  to  a  specific  docu¬ 
ment,  the  Programmer's  Maintenance  SanuaL,  and  how  it  should 
be  designed. 

1.  Commenting 

It  has  been  stated  that  one  objective  to  improve  the 
documentation  of  software  was  to  males  the  program  code 
itself  more  readable.  Twc  techniques  already  discussed  were 
structured  programming  and  the  use  of  higa  order  languages. 
A  third  technique  is  the  placing  of  comments  at  appeopiate 
places  within  the  program  code.  One  of  tae  main  a 


::  a  consistent  commenting  poncy  is  its 


.naecena 


the  prcgrammiia  language  used.  There  are  very  few 
tnat  do  net  allow  comments  to  be  placed  in  the 
[Ref.  40  ]. 

A  second  advantage  is  that  commenting  close 
between  computing  managers  and  computer  onogranmer: 


a:  ueve.o ps  because  cf  the  programme: 


attention  to  details.  These  details  include  such  items  as 
assembly  language  instruction  choices,  high  order  language 
statement  type  choices,  flag  initialization  procedures,  and 
the  design  of  nested  loops  with  if.. then  constructs  which 
implement  the  logic  of  the  software  system.  The  manager,  on 
the  other  hand,  must  keep  a  "Big -Picture"  perspective  of  the 
system  and  be  able  to  evaluate  an  elusive  entity  called 
software  quality.  Software  quality  is  often  based  on  items 
such  as  reliabilty,  readability  and  portablity  [Ref.  38]. 
In  order  to  evaluate  all  these  "-ilities",  the  manager  must 
be  able  to  read  the  program  listing  and  understand  the 
implementation  of  the  software  design  without  necessarily 
beinq  familiar  with  all  the  in’s  and  out's  of  a  particular 
program  language. 

Comments  assist  in  putting  more  documentation  into 
the  program  listing  as  well  as  making  the  program  more  read- 
ible.  Comments  explain  details  about  the  program  that  are 
not  appearent  from  the  code  itself.  Taole  IV  provides  a  list 
of  where  comments  should  appear  in  the  program.  One  DOD 
activity,  the  Marine  Cor  p '  s  Tactical  Systems  Support 
Activity,  has  had  a  great  deal  of  success  in  easing  its 
burden  or  software  maintenance  by  implementing  a  detailed 
commenting  policy.  Although  MOTSSA's  programs  are  mainly 
written  in  the  >Tavy's  CMS-2  language,  it  was  found  that  such 
a  policy  helped  reduce  the  amount  of  time  spent  by  program¬ 
mers  cr.  software  changes  in  aidition  to  the  time  savings 
achieved  by  the  use  of  a  higa  order  language.  [Ref.  48] 
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TABLE  I? 

Recommended  Locations  for  Comments 


1.  it  the  beginnning  of  earn  module.  include  the 
module  name,  the  currant  date,  the  module’s 
function,  its  inputs  and  outputs,  its  limitations 
and  restrictions,  including  assumptions,  its 
error  processes,  and  the  name  of  the  developer, 
iajor  modules  should  also  include  the  history 

of  modifications:  for  each  change,  the  date, 
the  maintainer's  name,  prupose  of  the  change 
and  scope. 

2.  it  each  subfunction,  whether  it  be  a  straight 
sequence  of  code  or  a  logic  branch  or  a  begin- 
etd  block,  an  explanation  of  that  subfuncf ion. 

3.  At  each  interface,  a  clear  definition  of  the 
interface  and  a  reference  for  further  infor¬ 
mation  about  the  other  side  of  the  interface 
(where  possible). 

4.  it  e>-ch  group  of  functionally  or  otherwise 
related  declarations,  an  explanation  of  the 
role  and  makeup  of  the  group. 

5.  At  each  declaration,  an  explanation  of  the  role 
of  the  item  and  the  meaning,  if  any,  of  its 
possible  values. 

6.  At  each  dif ficult-to-unde rstand  program  portion, 
ar.  explanation  of  what  the  code  does  and  why  a 
complex  solution  was  necessary. 


IV.  TOE  MAIN XI SISCS  MANOiL 


S 

\ 


1 

k 

s 


A.  OBJECTIVES  OF  A  MAINTENANCE  MANUAL 

In  order  to  determine  ho*  a  programmer's  maintenance 
manual  should  be  organized  it  will  be  helpful  to  examine 
some  specific  goals  that  apply  to  any  type  of  manual. 

1 .  General 

The  first  objective  is  to  enumerate  those  general 
organizational  qualities  of  writing  and  style  that  lead  to 
ease  of  use  and  readability  of  technical  publications  and 
documents.  There  are  several  factors  that  insure  the  infor¬ 
mation  contained  in  a  manual  are  is  easy  to  use.  These 
factors  can  be  characterized  into  two  broad  areas.  The  first 
area  concerns  the  concept  that  all  information  presented  by 
the  manual  be  easy  to  find  or  Locate.  The  second  area  is  the 
concept  that,  once  one  finds  tie  information,  the  informa¬ 
tion  is  readily  understood. 

The  factors  that  support  ease  in  finding  information 
are  consistency,  pointers  and  arrangement  [Kef.  50]. 
Consistency  is  the  principle  that  similar  objects  (i.e. 
maintenance  manuals)  containing  the  same  information  (how  to 
understand  and  change  a  computer  program!  be  presented  ir 
identical  ways.  In  ether  words,  all  manuals  should  have 
identical  formats.  Headers  of  the  manual  know  wnat  to 
=  :<oect,  how  to  lock,  for  specific  information  and  where  they 
will  find  it.  For  a  program  naintenar.ee  manual  it  would  be 
helpful  that  details  cn  data  structures  be  ir.  the  sane  loca¬ 
tion  in  each  sectior  cf  the  lanal. 


Pointers  are  essential  signposts  which  identify 
related  groups  of  information.  Pointers  ace  represented  by 
entities  such  as  tables  of  contents,  indexes  and  section 
headings  of  text.  Pointers  announce  the  presence  and  loca¬ 
tion  of  information  within  the  body  of  the  manual. 

Arrangement  refers  to  the  manner  of  presentation 
used  throughout  the  manual.  The  arrangement  anticipates  ways 
in  which  readers  might  look  for  specific  information.  The 
subject  of  a  manual  might  typically  be  arranged  by  alphabet¬ 
ical  or  chronological  order.  Subject  classification  is 
another  method.  For  a  program  maintenance  manual,  the 
arrangement  might  be  related  to  the  hierarchical  design  of 
the  main  functions  and  subfunctions  of  the  program  or  to 
some  external  criteria.  This  criteria  could  be  specified  by 
documentation  standards  incorporated  in  directives. 

The  factors  that  support  ease  of  understanding  are 
simplicity,  concreteness  and  naturalness  [Ref.  50]. 
Simplicity  is  the  concept  that  a  writer  saould  use  a  vocabu¬ 
lary  and  writing  style  “hat  suits  the  intended  readers. 
Admittedly,  one  assumes  that  any  paricular  person  having  the 
need  no  read  a  maintenance  manual  can  understand  fairly 
complex  compositions.  Still,  the  goal  of  simplicity  is  to 
keep  the  technical  "verbage"  to  a  minimum,  while  presenting 
a  clear  and  logical  flow  of  descriptive  information.  In 
addition,  a  dictionary  or  appendix  should  be  included  to 
supply  definitions  of  any  "buzzwords"  for  clarification  and 
consist*  nc y. 

Concreteness  ensures  that  verbal  descriptions  are 
more  specific  than  general.  It  also  implies  that  examples, 
diagrams  and  pictures  be  provided  for  amplification  and 
clarification.  For  program  maintenance  manuals  the  best  *-.vpe 
of  diagrams  tc  use  has  seen  a  long  history  of  controversy. 
Hierarchy  diagrams,  flow  smarts,  charts,  and 
NA  SSI-SC MZTDZr.2!A!l  charts,  amoag  others,  nave  seen  the  most 
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usage  * Hef.  51].  New  developments  such  as  structured 
program  design  languages  (PDL'sf,  automated  graphic  packages 
and  abstract  data  typing  for  the  design  process  are  now 
being  used  to  supplement  verbal  descriptions  of  the  software 
raef.  49]. 

The  concept  of  naturalness  provides  the  reader  with 
the  unfolding  of  information  in  an  ordered  manner.  It 
ensures  that  readers  can  verify  they  are  on  the  rigat  track 
and  will  ultimately  find  what  they  are  looking  for 
[Ref.  52  ]. 


2.  Record  of  Design 


The  second  objective  of  the  progn miner •  s  maintenance 
manual  is  to  provide  programmers  and  management  a  record  of 
the  philosophy  of  design  and  historical  development  of  the 
software.  The  manual  must  include  a  concrete  representation 
of  the  software  design  as  well.  Glass  [Ref.  43]  describes 
four  categories  of  documents  which  could  be  included  as  part 
of  a  maintenance  manual. 

•  design  NOTES 

Desian  notes  explain  now  and  why  sections  of  the 
software  evolved  into  their  present  state.  They  should  be 
prepared  in  seme  sort  of  stanaard  format,  filed  chronologi¬ 
cally  and  cross-indexed  to  the  program  code.  They  do  not 
have  to  be  detailed  but  should  provide  a  good  overview  of 
the  concepts  supporting  a  particular  design " approach. 

•  £30  51  EM  REPORTS 

Problem  reports  are  records  of  problems  encountered 
during  the  desian  process.  They  should  describe  the  problem 
and  its  ultimate  solution.  Thav  are  eventually  placed  in  a 
permanent  historic  file  once  the  final  design  is  fixed.  Ihev 
are  extremely  useful  in  isolating  errors  that  cccur  during 
system  testing. 

•  IMPROVEMENT  REPORTS 

Improvement  reports  are  suggestions  and  collections 
of  ideas  held  for  future  chances  to  be  inoococrated  into  the 
software  svstem.  Thev  can  be'majcr  improvements  or  oosmetio 
only.  A  reason  for  doing  this  is  to  pass  sound  ideas  of  the 
desianers  to  the  maintenance  programmers.  These  ideas  mav  be 
heloful  when  adding  enhancements  as  a  cesult  of  changes  in 
user's  requirements. 
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•  VERSION  DESCRIPTION 

Version  descriptions  are  numbered  changes  that 
describe  the  modifications  and  e nhacncamants  added  to  a  new 
release  of  the  software.  Each  numbered  change  should  have  a 
complete  list  of  the  changes,  where  they  ware  made  and  why, 
a  list  of  the  problem  reports  closed  and  a  description  of 
the  impact  of  the  changes  on  the  users  in  the  user's  terms. 

The  structure  and  description  of  the  software  system 
design  is  best  kept  as  single  and  straightforward  as 
possible.  Before  the  advent  of  structured  programming  and 
structured  design  tools  (such  as  Program  Design  Languages) 
there  was  no  standardized  manner  to  represent  the  software 
design.  This  is  still  a  problem  today,  especially  when  one 
desires  to  have  "proofs  of  correctness"  to  determine  that 
the  software  is  free  of  errors  ‘Ref.  49].  The  best  that  can 
be  done  is  to  use  a  combination  of  items  such  as  hierarch¬ 
ical  block  diagrams  to  list  the  major  modules  and  their 
control/data  flow  relationships,  grouping  of  data  item 
descriptions  into  "clusters"  based  or.  usage  of  the  data,  and 
coding  the  design  with  a  well  organized,  modularized  and 
readable  high  order  language. 

3.  Support  Maintenance  Programmer's  Tasks 

The  programmer's  maintenance  manual  should  be  the 
single  document  that  programmers  need  to  refer  to  for  soft¬ 
ware  maintenance  activities.  The  manual  has  to  be  complete 
in  that  it  must  contain  all  the  information  needed  by 
programmers  to  accomplish  their  two  primary  tasks; 
correcting  errors  (modification)  and  adding  new  capabilities 
(enhance sent)  . 

To  supoort  these  tasks  the  manual  should  be  a  well 
organized,  concise  and  thorough  description  of  •‘■he  software. 
It  jus*  contain  both  an  overall  design  view  and  a  discrete, 
detailed  procedure  by  procedure  view.  It  nas  to  describe  all 
all  data  items  ir.puted  tc  the  program  (type/format/range), 
-he  processes  performed  cr.  the  data,  and  the  type/format/ 
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range  of  the  output  data.  In  a  real-time  control  system 
where  the  software  performs  coatrol  functions  based  on  the 
parellel  processing  of  data,  the  logical  control  responses 
to  various  data  inputs  must  be  specified. 

Data  structure  and  organization  has  to  be  described 
in  detail.  Enumeration  of  data  nnmes,  descriptions  of 
tables  and  arrays  and  how  they  are  used,  initialized  or 
otherwise  manipulated  by  the  program  is  of  primacy  impor¬ 
tance.  Cross-reference  listings,  which  list  each  data  item 
and  every  module,  function  and  procedure  where  that  data 
item  is  used,  are  valuable  aides  for  understanding  the 
program. 

Finally,  two  general  guidelines  must  be  kept  in  mind 
if  the  manual  is  to  support  the  tasks  of  the  maintenance 
pcogriiujer .  First,  The  manual  must  provide  for  complete 
tracabiiity  from  the  user's  operational  requirements  to  the 
actual  program  listing  (lines  of  code)  so  that  if  a  require¬ 
ment  changes  then  the  appcopiate  coda  can  be  correctly 
changed,  deleted  or  new  code  added.  Second,  the  manual  must 
be  easily  modified  and  the  change  recorded  properly  in  order 
to  reflect  the  changes  to  the  software.  Ef  this  is  not  done 
the  manual  seen  becomes  outdated  and  useless  as  a  mainte¬ 
nance  *oci.  [Ref.  43  ,  51  ,  53  ] 

B.  DEPARTMENT  OF  DEFENSE  REQUIREMENTS 

How  the  objectives  of  a  maintenance  manual  are  best 
fulfilled  is  the  main  topic  of  this  tmesis.  DoD  currently 
requires  a  copy  of  the  pregram  listing  and  several 
suoportir.g  documents  for  representing  the  program  design. 
Different  DcD  agencies  have  different  requirements  for  docu¬ 
mentation  ar.d  various  names  *or  individual  documents.  The 
DoD  documents  briefly  described  here  are  from  the  standard 
that  describes  a  Program  Maintenance  Manual  for  all  CcD 
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activities  (DOD  STANDARD  7935. IS)  aad  those  U.S.  Navy  stan¬ 
dards  relating  to  software  maintenance  documentation. 

1.  Program  Maintenance  Manual 

A  description  of  the  DoD  requirements  for  a  program 
maintenance  manual  is  presented  in  DDD  STANDARD  7935. IS, 
"Automated  Data  Systems  Documentation  Standards,"  13 
September  1977.  The  standards  main  orientation  is  toward 
documenting  larg«  data  processing  systems,  however,  it  can 
be  used  for  imbedded  tactical  control  systems  as  well.  A 
copy  of  the  format  for  the  Program  Maintenance  Manual  is 
provided  in  Appendix  A. 

According  to  the  standard,  the  Maintenance  Manual 
(PMM)  is  to  be  divided  into  four  major  sections.  The  first 
section  is  required  to  give  a  general  iescription  of  the 
program;  its  purpose,  history  of  development,  and  define 
other  documents  used  to  support  the  program  (User's  Manual, 
etc.).  The  second  section  contains  a  system  description  to 
include  applications,  functions,  input/output  and  informa¬ 
tion  or.  summary  reports.  Details  and  char  a  cteristics  of  each 
procedure  and  subroutine  that  would  be  of  help  to  the 
maintenance  programmer  are  to  oe  stated.  Items  such  as  data 
record  types,  table  characteri sires,  exit  and  branching 
Dcocedures,  interfaces,  descriptions  of  working  and  output 
files  must  be  specified.  The  third  section  is  to  describe 
the  operating  environment  to  include  what  support  software 
is  needed.  This  section  is  also  to  contain  a  complete 
descripr.  rcr.  of  the  data  base  as  well  as  specifying  the 
storage  media  for  the  data  base  (tape,  disk,  or  internal). 
The  fourth  section  is  to  contain  information  on  specific 
maintenance  procedures.  This  wiLl  include  information  or.  the 
labeling  of  functions,  subroutines  and  data  records,  along 
with  the  programming  standards  utilized.  This  section  is  to 
contain  a  copy  of  the  program  listing  itself. 
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2.  Program  Desgr  ipticn  Docu  ment 

The  Program  Description  Document  (PDD)  is  esquired 
by  SECNAVINST  3560.1  .  Its  purpose  is  to  provide  a  complete 
technical  description  of  all  procedures,  functions,  data 
structurss,  operating  environment,  operating  constraints, 
and  data  base  organization  of  the  software  system.  The  PDD 
is  to  describe  and  completely  define  the  basic  program  logic 
and  program  procedures  for  earn  system  control  subroutine. 
The  PDD  is  also  required  to  be  directly  related  to  the 
program  design  specifications  which  are  the  formal  func¬ 
tional  requirements  of  the  software  system.  The  PDD  is,  in 
essence,  the  Navy's  version  of  a  DoD  program  maintenance 
manual.  The  PDD  does  not  contain  a  copy  of  the  program 
listing  or  a  complete  data  base  description. 

3.  Data  Ease  Des iqn  Document 

The  Data  Base  Design  Document  (DBDD)  is  required  by 
the  sa'ms  instruction  to  provide  a  complete  detailed  descrip¬ 
tion  of  ail  common  data  items  necessary  to  carry  out  the 
functions  of  the  software  system.  Domaon  data  is  defined  as 
that  data  required  and  used  oy  two  or  more  subprograms. 
Examples  of  common  data  include  constants,  indexes,  flags, 
variables  and  tables.  The  DBDD  is  to  be  based  on  the  func¬ 
tional  or  performance  specificat ions.  Ail  terminology  in  the 
DBDD  is  tc  conform  to  the  programming  guidelines  of  the 
program  design  specification  and  the  particular  programming 
language  employed.  The  DBDD  has  to  give  an  organized, 
detailed  descrio-icn  of  ail  i a ta  objects  to  include  such 
characterisitcs  as  purpose  of  tie  data  ooject,  field  name, 
size,  numeric  type  (fixed  point,  floating  point),  range  of 
values,  initialized  condition.  A  cross-reference  listing  of 
each  common  data  item  (fable,  flag,  etc.)  to  each  program  or 
subprogram  where  it  is  used  or  set  will  be  provided. 
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4.  Frogj dm  Pack  a  ge  Document 

The  Program  Package  Document  (PPD)  is  designed  to 
consist  of  all  the  program  aaterial  items  such  as  card 
decks,  magnetic  tape,  disk  packs  or  printed  listing  of  the 
software  instructions.  The  PPD  is  to  include  an  error  free 
listing  of  a  compilation  of  the  source  program  and  any  data 
which  is  necessary  for  the  program  to  run  properly.  Examples 
of  these  data  items  wculd  be  adaption  data,  data  file  cons¬ 
tants,  set-up  (initialization)  data  and  program  parameter 
val ues. 


5.  Problems  with  DDDJ.S  Regu  irements 


The  DoD  approach,  as  s 
7935. IS,  SECNAVINST  3560.  1,  and 
based  on  the  supposedly  "good  ma 
the  maintenance  documentation 
complete  set  of  English  text, 
proaram  is  compiled  into  volumes 
can  reach  several  feet  in  width, 
as  briefly  outlined  previously, 
exDiains  each  item  and  structure 
shows  control  flow,  data  flow,  m 
functions.  All  this  information, 
by  the  maintenance  programmer. 


tandardized  in  DoD  STANDARD 
MIL-STD-1  679  (Navy)  are  all 
nagement  practice"  of  having 
of  a  software  system  be  a 
Information  concerning  the 
taat,  in  complex  systems. 
All  tnis  text  information, 
gives  a  system  overview, 
in  the  system's  data  base, 
cdule  interfaces,  and  major 
in  and  of  itself,  is  usable 
However,  placing  it  in 


ssoerate  volumes  is  not  the  best  way  to  present  it.  This 
information  is  much  more  valuaole  to  the  programmers  when 
integrated  into  the  program  listing.  To  reiterate:  "... 
Document  at  icr.  information  about  a  software  system  oslongs, 
in  most  cases,  in  the  listing  of  the  program  itself." 
[Ref.  53]  There  are  three  key  reasons  wny  documentation,  to 
the  greatest  extent  possible,  snouli  be  placed  in  the 


program  ns 


The  first  reason  is  that  programmers  tend  to  dislike 
writing  documentation.  They  would  much  rather  be  writing 
code,  which  is  what  they  do  best  and  feel  the  most  comfor¬ 
table  with  [ Bef .  54].  If  the  documentation  is  an  integral 
part  of  the  listing  then  using  readable  data  names,  jotting 
down  a  few  lines  of  comment  to  explain  how  a  procedure  or 
function  works  and  structuring  the  code  becomes  a  much 
easier  task.  The  programmer  is  saved  frcm  the  tedious 
paper-work  drill  of  having  to  lock  up  a  separate  program 
maintenance  document,  figure  our  how  it’s  organized  and 
where  the  needed  information  is  and  then  submit  a  change 
outlining  what  program  modifications  or  enhancements  were 
made.  The  programmer  can  be  more  productive  by  combining 
two  steps  into  one  by  keeping  both  the  documentation  and 
program  code  up  to  date.  Having  the  code  ana  documentation 
together  car.  be  used  by  managers  as  a  motivation  factor  by 
demonstrating  less  work  for  the  programmers  in  the  long  run. 
Other  benefits  can  be  shown  as  in  the  case  of  using  a 
programming  team  to  develop  a  large  software  project.  Here 
the  team  can  design  the  documentation  as  they  design  the 
structure  of  the  software.  This  can  eliminate  the  need  for  a 
seperate  team  just  to  design  and  write  the  documentation. 
The  documentation  design  can  he  directly  related  to  ana 
supportive  of  tne  software  design. 

The  second  reason  for  placing  documentation  in  the 
listing  is  ‘c  enhance  managements  spaa  of  control.  As 
mentioned  earlier,  there  is  a  larae  requirement  for  managers 
to  keep  a  big-picture  view  and  be  aoie  to  supervise,  direct 
and  track  programmer's  activities  and  progress  while  they 
are  performing  maintenance  tasks.  The  documentation  ir.  the 
listing  provides  the  means  whereby  a  manager  can  evaluate 
changes  to  the  software  and  its  resultant  quality.  Managers 
would  no  longer  be  required  to  evaluate  changes  to  :  he  code 
an l  it's  associated  documentation  and  then  have  to  check  to 
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make  sure  the  docume rtat ion  change  correctly  reflects  the 

code  change.  In  essence  it  is  desired  to  avoid  a  "double- 

# 

entry  bookkeeping"  system  where  the  documentation  describes 
the  software  as  the  managers  and  programmers  think  it  works, 
and  the  listing  represents  how  the  software  actually  works. 
[Bef.  53] 

The  final  reason  is  that  a  program  maintenance 
manual  must  remain  accurate  and  valid  as  long  as  the  soft¬ 
ware  system  is  useful.  Programmers  must  be  able  to  quickly 
logically  use  the  documentation  to  understand  what  a  section 
of  code  is  accomplishing  and  how  it  is  doing  so.  Again,  if 
user's  requirements  change,  it  is  essential  that  the  soft¬ 
ware  be  changed  rapidly  and  in  an  error-free  manner  as 
possible.  If  a  maintenance  programmer  cannot  tell  how  the 
code  is  working,  changes  based  on  valid  user  needs,  or  for 
any  other  reason,  will  be  difficult  at  bast. 

C.  A  PROPOSED  "IDEAL"  8AINTENAHCE  SANOAL 

To  overcome  the  difficulties  with  updating  the  documen¬ 
tation  and  ensure  that  the  documentation  is  in  a  form  that 
is  readily  usable  by  programmers  and  managers  forces  one  to 
consider  a  revised  format  for  a  program  maintenance  manual. 
The  manual  contents  presented  here  are  based  on  the  advan¬ 
tages  inherent  with  the  quality  and  detail  that  the  DcD 
standards  require  and  those  advantages  gained  from  incorpo¬ 
rating  current  software  engineering  practices.  The  "Idsai" 
program  maintnenace  manual  will  be  divided  into  four 
sections:  (1)  Overall  Program  Structure,  (2)  The  Program 
Listing,  (3)  A  Data  Dictionary,  and  (U)  Supplemental 
ADoencices . 
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Qver^j.1  ?r  ogr  am  structure 

The  overall  program  structure  should  consist  of 
words  aid  pictures  indicating  how  the  satire  systsm  hangs 
together.  A  functional  block  diagram,  which  shows  all  major 
modules,  procedures  and  functions  is  essential.  This  diagram 
represents  the  system  structure,  the  execution  order  (if 
possible)  and  data  flow.  The  section  should  contain  a  well 
organized  index,  logically  arranged,  which  points  the  way  to 
detail  level  documentation  in  the  listing.  The  index  should 
reflect  the  block  diagram  and  the  design  of  the  system.  The 
index  should  locate  major  data  structures  and  data  clusters 
within  each  module.  This  section  should  contain  a  written 
text  introduction  to  the  overall  purpose  and  function  of  the 
software,  the  hardware  configuration  used  for  tests  and 
evaluation  prior  to  software  delivery,  and  the  target 
computer  system  (tactical  cr  data  processing)  the  software 
is  to  run  on.  Each  module  of  the  program  will  be  listed,  a 
brief  description  cf  the  module  given  and  the  functional 
relation  ships/interfaces  with  ocher  modules  completely 
annotated. 

Finally,  the  section  should  state  the  company 
responsible  for  the  program  design  and  development,  the 
names  of  the  chief  programmer  and  members  of  his  team  and 
aoolicaole  references  and  standards  used.  These  standards 
should  include  the  program  performance  spsci fications,  stan¬ 
dards  for  data  objects,  and  the  language  programming 
standards. 

2.  The  Program  Listing 

The  computer  program  listing  is  the  single  most 
important  tool  for  software  maintenance  activities.  The 
objective  of  the  maintenance  manual  is  to  maximize  t.ns  main¬ 
tainability  aspect  of  the  listing.  In  inis  regard  clarity 
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and  reaiibility  are  to  be  emphasized  over  efficiency.  It  is 
important  that  the  program  listing  be  clear,  concise,  struc¬ 
tured,  well  designed,  modularized  and  straightforward. 
[Ref.  48]  Each  module  should  contain  a  description  of  what 
the  module  does  and  what  procedures  or  functions  are 
contained  in  the  module.  Each  module  should  contain  a 
section  for  data  descriptions  or  declarations,  global  and 
local.  Table,  variable  and  flag  declarations  may  be  segre¬ 
gated  and  logically  grouped. 

a.  Physical  Layout 

Good  physical  layout  is  defined  as  '’...that 
property  of  a  program  listing  which  makes  it  capable  of 
being  read  and  understood  by  a  programmer  not  familiar  with 
the  program.”  [Ref.  48]  Good  readibility  may  be  achieved  by 
a  variecy  of  techniques,  some  of  which  ace;  seperation  of 
logically  related  groups  of  code,  seperation  comments  and 
code,  blocking  (by  using  lines  of  asterisks)  lengthy 
comments,  the  appropiate  use  of  blank  lines,  logical  inden¬ 
tation  and  the  lining  up  of  begin-er.d,  if-then/else  pairs. 

All  the  tenants  of  structured  programming  ,  as 
discussed  ir.  Chapter  III,  are  key  ingredients  of  good 
physical  layout.  Figures  3.3  and  3.5  illustrate  this 
physical  structure.  It  may  be  imposed  on  the  code,  as  with 
assembly  language,  or  be  part  of  the  language  syntax,  as 
with  ADA .  [Ref.  38  ,  39  ,  42] 

b.  Commenting  and  Naming 

The  use  cf  meaningful  commsnts  is  of  primary 
imDortance  to  increase  understanding  of  the  program. 
Comments  should  explain,  amplify  and  supplement  tha  listing 
rather  then  echo  the  code.  For  example; 

N  =  N  ♦  1  --Increment  N 


O  w 


—  A  message  has  just  been  inserted  into  the  message 

—  queue. 

--  increment  Msg  OUEOE  Pointer  so  that  it  points  to 

—  the  location  Unere  fhe  next  message  may  be 

--  inserted. 

Msg_2 OEOE_Pointer  =  Msg_Queue_Pointer  «■  1 

i - - - i 

Figure  4.1  An  Example  of  Heaningfal  Comments. 

does  nothing  to  explain  why  N  is  being  incremented.  A  better 
example  is  illustrated  by  Figure  4.1  . 

If  a  program  module  consists  of  more  than  cne 
procedure  or  function  then  there  should  be  commentary  for 
each  procedure  or  function.  The  comments  for  each  procedure 
and  function  should  contain  an  extensive,  detailed  descrip¬ 
tion  of  how  the  procedure  operates  and  its  purpose  in  the 
module.  The  sequence  of  processing  shouLd  be  described  in 
chronological  order  to  include  the  calling  sequence  of 
control.  The  hierarchical  structure  of  the  module  can  be 
reflected  in  a  like  manner  as  comments  follow  the  physical 
indentation.  Table  III  lists  other  criteria  for  commenting 
as  discussed  earlier. 

All  names  for  data  objects,  modules  and  proce¬ 
dures  must  be  descriptive  in  nature.  They  should  attempt  to 
embody  the  character! sites  of  the  data  item  they  represent. 
Names  such  as  ID_Buffer,  SI!13_?u  action  and  ?A?_Roli_5UH  have 
inherent  meanings  and  are  easier  for  the  programmer  to  trace 
through  the  listing.  Names  such  as  A ,  X,  N,  or  XYZ  are  mean¬ 
ingless.  Related  data  items  and  procedures  should  have 
related  names  which  demonstrate  their  interconnections. 
fRef.  43,  44,  48  ] 


c.  Data  Declarations  and  Definitions 


All  data  items  should  be  grouped  and  organized 
according  to  their  logical  usage.  Global  data  elements 
should  be  defined  in  one  location.  Local  data  elements  are 
to  described  in  the  procedure  where  they  are  manipulated. 
The  technique  of  information  hiding,  where  the  structure  and 
characteristics  of  local  data  aid  parameters  are  unknown  to 
procedures  in  other  modules  [Ref.  24  ],  is  to  be  utilized  to 
the  maximum  extent. 

If  the  programming  language  does  not  support 
strong  data  typing  for  data  declarations,  as  in  the  DoD  high 
order  language  ADA,  then  variable,  table,  array  aid  other 
data  declarations  must  contain  meaningful  comments.  These 
comments  are  to  describe  the  purpose,  initial  value,  range 
and  distinct  structure  of  eaca  data  element.  Figure  4.2 
reveals  how  a  data  table  (or  record)  would  be  declared  in 
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type  MONTH  NAME  is  (JAM,  P  EB,.M  AR,  APR  ,  M  AY,  JON, 

JUL, A UG ,5SP, DCT , NOV, DEC)  ; 


type  DATE  is 
~eco~d 

DAY:  INTEGER  raue  1.  .31; 
MONTH :  MONTH  NAME 
YEAR:  INTEGER 
end  record; 


Figure  4.2  Example  of  an  ADA  Data  Table  (Record) . 

ADA.  The  table  is  called  'DATS*  and  has  three  components 
named  'DAY',  'MONTH',  and  'YEAS'.  DAY  aid  YEA?  are  defined 
to  be  of  type  INTEGER.  MONTH  has  a  separate  type  ieclara- 
tion  called  HC  NTH_MAH  E.  INTEGER  is  assumed  to  be  defined  by 


the  support  software  of  the  system  and  having  the  mathemat¬ 
ical  characteristics  cf  all  integer  numbers.  Variables  and 
constants  associated  with  the  table  HIE  can  then  be 


Comment 

TABLE  ACCOUNTS 

—  Used  to  store  info 
accounts.  Consists 

1.  ACCOUNT  NAME  (ACCTN 
—  Contains  u? 


2.  ACCOUNT  NUM BES  (ACC 

—  Ranges  form 
numeric  type 

3.  BALANCE  (BALANCE) 

—  Ranges  form 
dollars  and 
REAL. 

4.  FLA3  (ACTIVE) 

--  When  TRUE  (= 
When  Falsa  ( 
use.  Is  of  L 

Misce  liar.e  o  3  s 

—  It.  program  initial! 
entire  table  is  flu 
Indices  (or  ooinfer 
table  are  the  named 
NIXTACCT  and  NEW  All 

TABLE  ACCOGNTS  V  DENSE  400  5 
FIELD  ACCT  NAME  H  20  3 

FIELD  ACCTNR  I  14  3 

FIELD  BALANCE  A  22  S  7  $ 

FIELD  ACTIVE  3  3 

END-TABLE  ACCOUNTS 


rmation  on  400  Bank 
of  four  elements. 

AMSi 

to  40  ASCII  characters. 
TNRl 

Zero  to  9999  and  is  of 
INTEGER. 


-9999.99  to  9999.99 
is  of  numeric  type 


1)  ,  Account  is  in  use. 
=0) ,  Account  is  not  in 
ogical  type  BOOLEAN. 

zation  tine  the 
shed  (set  to  ZERO)  . 
s)  related  to  this 
variables  LAST ACCT, 

T.  S 


Figure  4.3  Example  of  a  CMS-2  Data  Table. 


defined.  An  example  would  be  a  variable  named  'D'  belonging 
to  type  DATE.  3efore  D  is  used  or  initialized  it  must  be 
further  defined.  This  is  don?  by  by  denoting  D  with  a  dot 
followed  bv  the  component  name  as  in:  (D.DAf:=  u;), 

(D. MONTI:-  JUL;) ,  and  (D.YSAR:=  1775).  I:  is  clear  that  all 
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X 
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the  attributes  of  the  table  called  DATE  are  readily  apparent 
to  the  maintenance  programmer.  The  reaiiDility  of  each  data 
object  clarifies  the  purpose  and  structure  of  t^e  table. 
[Ref.  4£A  ]  Figure  4.3  gives  an  example  of  a  common  way  to 
declare  a  table  using  the  Navy's  CM5-2  programming  language. 
The  use  of  clear  and  concise  comments  fulfills  similar 
objectives  as  data  typing  in  ADA. 

3.  A  Data  Dictionary 

A  data  dictionary  provides  descriptions  of  indivi¬ 
dual  data  entities  and  can  be  used  as  an  index  as  to  where 
the  data  elements  are  declared  in  the  program  listing.  This 
is  extremely  useful  for  large  programs,  i.e.,  greater  than 
10,000  lines  of  code.  The  data  dictionary  can  and  should 
provide  the  formats  for  the  declaration  of  data  within  the 
program  while  being  a  catalog  of  the  data  resources  of  a 
software  system.  [Ref.  55] 

The  data  dictionary  defines  the  logical  organization 
and  physical  organization  of  tie  system's  data  entities.  The 
logical  organization  specifies  requirements  for  data  access, 
modifier  ~ion,  associativity  and  other  system  orientated 
concerns.  The  physical  organization  defines  file  structures, 
record  formats,  hardware  dependent  processing  features  and 
database  management  characteristics.  All  data  structures  and 
the  operations  that  are  to  be  performed  on  each  structure 
should  oe  identified  in  the  dictionary.  Tie  program  listing 
can  be  referenced  for  details  on  data  elements  and  those 
functions  or  operations  dependent  on  these  elements.  A  data 
dictionary  can  explicitly  represent  the  relationships  among 
data  and  the  constraints  these  elements  place  on  data 
structures.  Algorithms  that  may  take  advantage  cf  specific 
data  relationships  can  be  more  easily  designed  and  modified 
if  a  dictionary- like  data  specification  exists.  [Ref.  56] 
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It  is  appropiate  that  the  data  dictionary  reflect 
the  structure  of  the  program  listing  as  closely  as  possible. 
The  concept  of  "mapping"  the  iictionary  onto  the  listing 
ensures  the  consistency  required  by  maintenance  actions.  It 
is  critical  to  the  maintenance  programmer  to  know  which  data 
items  effect  which  particular  modules  and  vice  versa.  A 
carefully  designed  and  integrated  data  dictionary  is  an 
essential  tool  for  any  modifications  or  enhancements  to  the 
software . 


4 .  Appendices 


This  section  of  the  maintenance  manual  is  to  contain 
that  supplementary  information  which  is  of  a  historical 
nature.  Examples  would  be  notes  on  the  development  of  the 
software  design,  problem  reports  ana  improvement  reports  as 
described  by  Glass  [Ref.  43],  In  a  separate  appendix  could 
be  a  complete  description  of  the  intended  operating  environ¬ 
ment,  hardware  configuration  and  operating  system  support 
desired  or  required.  A  continuous  file  of  each  version 
release  and  a  loq  of  ail  changes  made  to  the  program  (who 
made  them  and  for  what  re  a  son)  should  be  included. 
[Ref.  43,  42,  48] 

A  final  appendix  should  contain  a  set  of  standards 
for  commenting,  algorithmic  structures,  and  the  data 
iictionary.  The  standards  for  commenting  are  useful  for 
consistency  and  to  enforce  reacioiiity  of  -he  listing. 
Standard  algorithmic  structures  provide  a  framework  for  the 
develcomer.t  of  module  libraries.  Such  libraries  can  be 
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accomplished  by  specifying  the  flow  and  storage  locations  of 
data  entities  within  the  organization  or  within  the  computer 
installation  (Ref.  55].  Standards  for  a  data  dictionary  can 
also  provide  a  library  of  standardized  data  structure  temp¬ 
lates  to  be  used  for  representing  the  Logical  and  physical 
characteristics  of  data  entities  within  the  software  system 
database  [Ref.  56]. 


V.  CO NCJ, 05 JONS  kM  SICONgEgD&riONS 


The  Department  of  Defense  has  an  argent  requirement  to 
reduce  the  costs  of  software  maintenance  during  the  coming 
decade.  Recent  advancements  in  the  methods  cf  software 
engineering  such  as  modularization,  structured  design, 
structured  programming  and  data  abstraction  have  contributed 
to  greater  program  comprehension.  This  increased  comprehen¬ 
sion  leads  to  easier  modifications  to  meet  a  dynamically 
changing  environment. 

It  is  the  opinion  of  this  author  that  the  benefits 
obtained  from  proven  software  engineering  practices  can  be 
realized  in  the  program  maintenance  manaaL.  These  principles 
can  and  should  be  applied  to  the  design  and  standards  for 
such  a  manual.  The  information  available  strickly  from  the 
program  code  itself  forces  us  to  question  the  practice  of 
keeping  the  documentation  seperate  from  the  code,  and  leads 
to  the  conclusion  that  it  should  not  be  seperate  but 
integrated  into  the  listing. 

With  this  in  mind  the  following  recommendations  are  put 
forth: 

•  The  Dresen'1:  standards  for  software  documentation  be 
revised  to  incorporate  the  most  useful  aspects  of 
recent  software  engineering  technology. 

•  Studies  should  be  undertaon  with  the  goal  of  standard¬ 
izing  terminology  for  software  maintenance  documents 
among  all  DoD  activities. 

•  A  framework  has  been  oroposed  for  a  orcgram  maintenance 
manual.  This  framework  shoila  be  imolemented  and 
tested  or.  various  size  and  tvces  of  software  systems  to 
discover  what  savir.as  in  'time  and  monev  can  oe 
achieved. 
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SECTION  1 


GENERAL  DESCRIPriON 


1.1  Purpose  of  the  Program  1ainter-aa.ee  Manual.  This 
paragraph  sKall  describe”  £Ke~  “pur  p? 3 e  or  the  MM 
(Program  Maintenance  Manual*  in  the  following  words  or 
appropiate  modifications  thereto: 


The  objective  for  writing  this  Program 
Maintenance  Manual  for  (Project  Name)  (Project 
Number)  is  to  provide  the  maintenance  programmer 
personnel  with  the  information  necessary  to 
effectively  maintain  the  system. 
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a.  Users  Manual. 

b.  Computer  Operation  Manual. 

c.  Other  pertinent  documentation  on  the 
pro  ject. 


1.3  Terms  and  Abbreviations.  This  oaragraph  shall 
provide  a  list “dr  include  in  an  aopsiiir  any  terms* 
definitions  or  acronyms  unigue  to' this  document  ana 
subject  tc  interpretation  by  the  user  of  the  document. 
This  list  will  not  include  item  names  or  data  codes. 


SECTION  2.  SYSTEM  DESCRIPTION 
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2-1  System  Application.  The  purpose  of 
the  functions  it  performs  shall  be  expl 
cular  application  system,  for  example, 
control  mission  activities  by  acre 
inputs  (status  reports,  emergency 
extracting  items  of  data,  aid  deriving 
data  g.n  o?de?  to  produce  both  mfoc 
specific  mission  and  information  for  s 
These  functions  shall  be  related  to 
Specific  Performance  Requirements,  an 
Functions,  of  the  FD  (Functional  Descri 


the  system  and 
ained.  &  parti- 
might  serve  to 
pting  specific 
conditions) , 
other  items  of 
nation  about  a 
ummary  reports, 
paragraphs  3.  1, 
a  3.2,  System 
ption) . 


This 
a  ponents 


2.2  Security 

describe  the  _ _ _  _ 

including  inputs,  outputs,  data 

ams.  it  will  also  prescribe  any  privacy 
associated  with  the  use  of  the  data. 
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2.3  Seneral  £esgr iption .  This  paragraph  will  provide 
a  comprehensive  description  of  tie  system  .  subsystem, 
jobs,  etc.  in  terms  of  their  overall  functions.  This 
description  will  be  accompanied  by  a  chart  showing  the 
interrelationships  of  the  major  components  of  the 
system. 
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Identification  -  program  lumber  or  tag 
including  a  designation  of  the  version 
number  of  the  program. 


Functions  -  description  of  program 
and  method  used  in  the  program' to 


the  function. 


functions 

accomplish 


Input  -  description  of  the  input.  Descriptions 
here  must  include  all  information  pertinent  to 
maintenance  programming.  including: 

(1)  Data  records  used  dv  the  program  during 
operation 

(2)  Inpu*  data  type  »  nd  location  (s)  used  by 
the  program  when  its  operation  begins. 

ring  the 


(3)  Entry  requirements  concern: 
initiation  of  the  program. 


< _ 


3.  Processing  -  description  of  the  processing 
performed  by  the  program,  including: 

(1)  Major  operations  -  the  major  ooerations  of 
program  will  be  described.  The  description 
may  reference  chart(si  which  may  be 
included  in  an  appendix.  This  chart  will 
show  the  general  logical  flow  of 
operations,  such  as  read  an  input, 
access  a  data  record,  major  decision,  and 

Erint  an  output  waicn  would  be  represented 
y  segments  or  subprograms  within  the 
program.  Reference  may  be  made  to  included 
charts  that  present  each  major  operation 
in  more  detail. 

(2)  Major  branching  conditions  provided  in 
the  program. 

(3)  Restrictions  that  have  been  designed  into 
the  system  with  respect  to  the  operation 
of  this  program,  or  any  limitations  on 
the  use  of  the  program. 

(4)  2xit  requirements  concerning  termination 
of  the  operation  of  the  program. 

(5)  Communications  or  linkage  to  the  next 
logical  program  (operational,  control}. 

(6)  Output  data  type  and  location  (s) 
produced  by  the  program  for  use  by 
related  processing  segments  of  the 
system. 

(7)  storage  -  Specify  the  amount  and  tyDe  of 
storage  required  to  use  the  program  and 
the  broad  parameters  of  the  storage 
locations  needed. 

e.  Output  -  description  of  the  outputs  produced 
by  the  program.  While  this  description  may 
reference  output  described  in  tie  Users  Manual, 
any  intermediate  output,  working  files,  etc. 
should  be  described  for  the  benefit  of  the 
maintenance  programmer. 

f.  Interfaces  -  description  of  the  interfaces  to 
from  this  program. 

g.  Tables  and  Items  -  provide  details  and 

characteristics  of  tie  tables  aid  items  within 
each  program.  Items  not  part  of  a  table  must 
be  listed  seoerately.  Items  contained  within 
a  tab+e  may  be  referenced  from  the  table 
■descriptions.  If  tie  data  descriotion  of  the 
program  provides  sufficient  information,  the 
program  listing  may  be  referenced  tc  provide 
some  of  the  necessary  information.  At' least 
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the  following  will  be  included  foe  each  table: 


Tabl  e 

Full 

Other 

Logic 

(inte 

entri 

Basic 

lengt 

struc 

Table 

shoul 

descr 

infor 

each 

char  a 

and  i 

locat 

Items 

speci 

that 

manip 

sense 

machi 

than 

impor 

of  ea 

will 


tag,  lable 
name  and  pu 
programs  t 
al  division 
rnal  table 
es)  . 

table  stru 
h,  fixed  or 
ture) . 
layout  f  a 
d  be  usedi  . 
iption  shou 
nation,  dat 
type  or  ant 
cteristics 
nf  ormation 
ions  of  it  a 
-  the  term 
fic  categor 
is  coded  fo 
ulation  by 
,  the  defia 
r.e-  and  pro 
operatioha 1 
tance  is  an 
ch  item,  it 
be  included 


or  symbolic  name, 
rpose  of  the  table, 
hat  use  this  table, 
s  within  the  table 
blocks  or  parts  -  not 

cture  (fixed  or  variable 
variable  entry 


graphic  o 
Included 
la  be  tabl 
ails  of  th 
rv,  unique 
of  the  usa 
about  the 
ms  within 
"item"  ra 
y  of  datai 
r  direct  a 
a  program, 
ition  of  a 
gram-orien 
ly  orients 
explanati 
least  tha 
for  each 


c esent ation 
in  supporting 
a  controlling 
a  structure  of 
or  significant 
of  the  table, 
names  and 
the  table, 
fers  to  a 
lad  information 
nd  immediate 
Used  in  this 
n  item  is 
ted  rather 
d.  Of  primary 
on  of  the  use 
following 
item: 


Item  tag  or  label  aid  full  name. 
Purpose  of  the  item. 

Item  coding,  depending  upon  the 
item  type,  such  as  integer, 
symbolic,  status,  etc. 


h.  Ur.iaue  Hun  Features  -  description  cf  any 
unique  features  of  tae  running  of  this 
proaram  that  are  not  included  ii  the 
Computer  Operation  Manual. 


SECTION  3.  ENVIRONHENT 

3.1  Equipment  gQ  vjL^onmeqt,  This  oaragraph  shall 
ailcuss  the”  equi pmenf”c5nfig uration  and  its  general 
characteristics  as  they  apply  to  the  system. 

3.2  Support  Software.  This  paragraph  shall  lis*  the 
various  support  sold  ware  asei  By  the  system  and  iden- 

nnier  which  the 


3.2  Support  Software.  This  paragraj 
various  support  software  used  By  the 
tify  the  version  or  release  number 
system  was  developed. 

3.3  Data  B§ge.  Information  in  this 
Include”  a”  complete  description  of 
content  of  each  data  base  used  by  the 


paragraph  shall 
the  nature  and 
system. 


3.3.1  General  Characreristi  cs. 
aescripfion  of  fEe  character Ifti 
including; 


Provide 
cs  of  the 


a  general 
data  base. 


Identification  -  name  and  mnemonic  reference 


b.  Permanency  -  note  whether  the  component 
contains  static  data  that  a  program  can 
reference,  but  may  not  change,  or  dynamic 
data  that  can  be  changed  or  updated  during 
system  operation.  Indicate  whether  the  chang* 
is  periodic  or  random  as  a  function  of  input 
data. 


.  Storage  -  specify  the  storage  media  for 
data  base  (e.g.  tape,  disk,  internal  st 
and  the  amount  of  storage  required. 


the 

orage) 


d.  Restrictions  -  explain  why  limitations  on 
the  use  of  this  component  by  the  orogram  in 
the  system. 

3.3.2  Organization  and  Detailed  Description.  This 
paragraph  will”sef ve'f o  define  fhe'Inf ernal”struccure 
of  the  data  base.  A  layout  will  be  shown  and  its 
composition,  such  as  records  and  tables,  will  be 
explained.  If  available,  computer  generated  or  other 
listings  af  this  detailed  information  may  be  refer¬ 
enced  or  included  herein.  The  following  items  indicate 
the  type  of  information  desired: 


Layout  -  show  the  stricture  of  the  data  base 
including  record  and  items. 

Sections  -  note  whether  tie  physical  record 
is  a  logical  record  or  one  of  several  that 
constitute  a  loaical  record.  Identify  the 
record  parts,  such  as  healer  or  control 
segments  and  the  body  of  the  record. 


Cop7  available  lo  DTIC  does  not 
Permit  fully  Itfbl,  IepIoduc1ion 


c.  Fields  -  identify  sash  field  in  the  record 
structure  and,  if  necessary,  explain  its  purpose. 
Include  for  each  field  tie  following  items: 

(1)  Tag$/labels  -  indicate  the  tag  or  label 
assigned  to  reference  each  field. 

(2)  Size  -  indicate  the  length  and  number  of 
bits/characters  that  maite  up  each  data 
field. 

(3)  Sange  -  indicate  the  range  of  acceptable 
values  for  the  field  entry. 

d.  Expansion  -  note  provisions,  if  any,  for 
adding  additional  data  fields  to  the  record. 
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SECTION  4.  PROGRAM  MAINTENANCE  PROCEDURES 


Section  4  of  the  manual  shall  provide  information  on  | 
the  specific  procedures  necessary  for  the  programmer 
to  maintain  the  programs  that  make  up  the  system. 

4.1  Conventions.  This  paragraph  will  explain  all 
rules 7  scEemesT  and  conventions  that  have  been  used 
within  the  system.  Information  of  tais  nature  could 
include  the  rollowing  items. 

a.  Design  of  mnemonic  identifiers  and  their 

application  to  the  tagging  or  labeling  of 
programs,  subroutines,  records,  data  fields, 
storage  areas,  etc.  I 

b.  Procedures  and  standards  for  charts,  listings,  i 

serialization  of  cards,  abbreviations  used  m  i 
statements  and  remarks,  and  symbols  appearing  I 
in  charts  and  listings.  ; 

I 

c.  The  appropiate  standards,  fully  identified,  I 

may  be  referenced  in  lieu  of  a  detailed  ouiine 

of  conventions. 

I 

d.  Standard  data  elements  and  related  features.  I 

4.2  Verification  Procedures.  This  paragraph  will 
Inclu <Je“tliose  regu ire  mends  “an d  procedures  necessary  to  i 
check  the  performance  of  a  program  section  following  | 
its  modification.  Included  may  also  be  Drocedures  for  | 
the  periodic  verification  of  the  program! 

4.3  Error  Conditions.  A  description  of  error  condi¬ 
tions!  net  previously  documented,  may  also  be 
included.  This  description  shall  include  an  explana¬ 
tion  of  the  source  of  the  error  and  recommended 
methods  to  correct  it. 

u.4  S Decial  Maintenance  Procedures.  This  paragraph 
shaII~cof tain  any  special  procedures  required  which 
have  not  been  delineated  elsewhere  in  this  section. 
Specific  information  that  may  be  appropiate  for 
presentation  shall  include: 

a.  Reguir emer.t s,  porcedures,  and  verification 
which  may  be  necessary  tc  maintain  the  system 
incut-output  components,  such  as  the  data 
base. 

b.  Requirements,  procedures,  and  verification 
methods  necessary  to  perform  a  Library 
Maintenance  System  ran. 

4.5  Special  Maintenance  Pcnorams.  This  paragraph 
shall  cor.tain“an  inventory”!  “any  soecial  oro grams 
(such  as  file  restoration,  purging  historical  files) 
used  to  maintain  the  system.  These  programs  should  be 
described  in  the  same  manner  as  those  described  in 
paragraphs  2.3  and  2.4  of  the  MM. 
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a.  Input-Output  Requires ents . 

IncluJea”tn-  tall  shall  oe  the  require¬ 
ments  concerning  the  equipment  and  materials  needed  to 
support  the  necessary  maintenance  tasks.  Materials 
may,  for  example,  include  card  decks  for  loading  a 
maintenance  program  and  the  inpurs  which  represent  the 
changes  to  be  made.  When  a  support  system  is  being 
used,  this  paragraph  should  reference  the  appropiate 
manual. 

b.  Procedures 

The  procedur e§7  presented  in  a  step-by-step  manner, 
shall  detail  the  method  of  preparing  tie  inputs,  such 
as  structuring  and  sequencing  of  inputs.  The  opera¬ 
tions  or  steps  to  be  followed  in  setting  up,  running, 
and  terminating  the  maintenance  task  on  the  equipment 
shall  be  given. 

4.6  Listings.  This  paragraph  will  contain  or  provide 
a  reference-  to  the  location  of  the  program  listing. 
Comments  appropiate  to  particular  instructions  shall 
be  made  if  necessary  to  understand  and  follow  the 
listing . 
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